Rich content and HTML
Memos store source text. Use the supported Markdown syntax for rich content, and patch that source through the normal editing workflow. Saving source and verifying its visible rendering are separate checks.
Highlights and text color
:highlight[...] adds a background tint; the default is yellow. :color[...]
changes the text color. Raw <span style="..."> is not a substitute: Memos do
not enable arbitrary HTML/CSS styling.
Directive content is plain text, including any Markdown markers. Escape brackets and backslashes with a backslash. Colors must be quoted supported names or 3-, 4-, 6-, or 8-digit hex values. Invalid colors and unknown attributes remain literal. Attribute-only forms also work:
Rendering support differs by surface. The app supports these directives; CLI/API HTML snapshots currently preserve color directives as source text. Check the Markdown authoring guide for supported colors, tables, references, and current rendering limits.
Highlight metadata from the CLI
user and comment are optional quoted strings. Use the canonical public user
handle, such as geyang, rather than an internal user ID or display name. A single
leading @ is accepted without rewriting saved source. The app resolves exact
personal-profile handles for sidebar names and avatars; missing profiles and
legacy names remain unresolved, with no fuzzy account matching. Attribution is
self-declared and does not verify authorship or grant access.
Metadata is plain text; JSON escaping supports \", \\ and \n. Duplicate or
unknown attributes and malformed quoting keep the directive literal. Existing
colors and plain highlights are unchanged.
Use the existing inline/sidebar comments toggle to review annotations. Sidebar
mode shows comment cards; clicking the highlighted text or a sidebar reveal
action exposes its Markdown source. Read-only memos expose no edit controls.
In the sidebar, done removes a highlight and its comment while keeping the
passage text. It is an undoable editor change; read-only memos have no Done
control. Insert, delete, and replace suggestions keep their separate accept/reject
actions. Connectors follow the annotation color, and hovering a card emphasizes
its passage and line in either theme. These browser controls require a frontend
including de637cdb; the CLI source syntax is unchanged.
Both supported forms can carry a comment:
Attribute-only comments require a frontend containing the scanner fix from
752c4df2 to appear in the comment rail. Both forms are accepted as Memo source
by CLI 0.86.1; frontend rendering and CLI storage support are separate.
No dedicated highlight command is needed. memos create --text or --file stores
the syntax, and memos replace edits it by matching text. Set MEMO_ID to the
ID returned by create/list. This complete example annotates an existing highlight:
The replacement helper needs the legacy ETag, not a v2 rtc: revision. Exactly one
match is expected; if the memo changed, read again before retrying. Do not rewrite
the whole memo to edit one annotation. These commands already support the syntax;
CLI 0.31.3 updates the bundled guidance, not the memo storage API.
References and placeholders
Keep existing raw memo references intact:
Use an actual accessible memo ID, not that example ID. Do not convert references into guessed URLs or silently replace their source syntax. The authoring guide is the reference for newer directives and development-preview features.
Short bracket placeholders such as [ owner name ] render as placeholders in
the app. Preserve their source when patching surrounding text. Rendered chips,
generated labels, and editor decorations are not replacement document source.
Read a rendered HTML snapshot
The CLI writes the complete server-rendered HTML byte-for-byte, with no text metadata prefix, JSON wrapper, or added newline. It validates the memo identity, source hash, and revision before emitting output. To inspect the acknowledged result of an edit:
A revision mismatch exits 3 without output. HTML reads require the matching
server contract and CLI 0.26.2+. They cannot be combined with --json, --since,
--format, --legacy, --linger, or partial/numbered reads.
Map an element back to source
| Attribute | Meaning |
|---|---|
Root data-note, data-hash, data-revision | Memo and snapshot identity |
Root data-source-type, data-offset-unit, data-source | Canonical source and its encoding/unit contract |
Element data-start, data-end, data-map | Source range and mapping kind |
Decode the root source attribute exactly once. Offsets count Unicode code points, not DOM UTF-16 units. Atomic mappings require whole-range edits; generated content has no editable source range. Use the mapped canonical source and original revision to prepare a patch. Never upload preview wrappers or metadata as the memo body.
For attaching an HTML file with its own preview URL, see Attachments.