Markdown formatting

OpenClaw converts outbound Markdown into a shared intermediate representation (IR) before rendering channel-specific output. The IR keeps plain text plus style/link spans, so one parse step feeds every channel and chunking never splits formatting mid-span.

Pipeline

1. Parse Markdown into IR (markdownToIR) - plain text plus style spans (bold, italic, strikethrough, code, code block, spoiler, blockquote, heading 1-6) and link spans. Offsets are UTF-16 code units so Signal style ranges align with its API directly. Tables parse only when the channel opts into a table mode.
2. Chunk the IR (chunkMarkdownIR / renderMarkdownIRChunksWithinLimit)
   • style and link spans are sliced with the text. The rendered-size chunker measures each candidate after channel escaping and link rewriting, and returns the accepted source slice together with its rendered payload.
3. Render per channel (renderMarkdownWithMarkers) - a style-marker map turns spans into the channel's native markup.

Raw inline HTML lexemes retain their original bytes during parsing. Markdown markers and entities inside attribute values or recognized inline comments are not parsed as Markdown content. Non-serialized authored-tag ranges let HTML-aware renderers interpret those tags; other renderers keep them literal or escape them. HTML block parsing stays disabled so Markdown inside containers still works, and bare URLs in their bodies retain normal linkification.

Examples of shared IR renderers:

IR example

Input Markdown:

Hello **world** - see [docs](https://docs.openclaw.ai).

IR (schematic):

{  "text": "Hello world - see docs.",  "styles": [{ "start": 6, "end": 11, "style": "bold" }],  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]}

Table handling

markdown.tables controls how a channel converts Markdown tables, per channel and optionally per account:

Inline code in table cells keeps its parsed content, including leading and trailing spaces, in every enabled table mode.

Per-channel plugin defaults: Matrix defaults to block (native tables); Mattermost defaults to off; Signal and WhatsApp default to bullets; Telegram defaults to block (which resolves to code unless the account has richMessages enabled). Any channel without an explicit plugin default falls back to code.

channels:  discord:    markdown:      tables: code    accounts:      work:        markdown:          tables: off

Chunking rules

• Chunk limits come from channel adapters/config. chunkMarkdownIR limits IR text; renderMarkdownIRChunksWithinLimit measures the final payload in the transport's size unit, including escaping and rewritten links.
• Fenced code blocks are kept as one block with a trailing newline so channels render the closing fence correctly.
• List and blockquote prefixes are part of the IR text, so chunking never splits mid-prefix.
• Paragraphs, headings, and code blocks inside a list item stay separated in the IR, including paragraphs nested inside a quoted list item.
• Inline styles never split across chunks; the renderer reopens an open style at the start of the next chunk.

See Streaming and chunking for chunk-boundary and delivery behavior across channels.

Link policy

• Slack: [label](url) -> <url|label>; bare URLs stay bare.
• Telegram: [label](url) -> <a href="url">label</a> (HTML parse mode).
• Signal: [label](url) -> label (url) unless the label already matches the URL.

Spoilers

Spoiler markers (||spoiler||) are parsed for Signal (mapped to SPOILER style ranges) and Telegram (mapped to <tg-spoiler>). Other channels treat ||...|| as plain text.

Collapsible details

The Control UI and Telegram accounts with richMessages: true render <details><summary>Label</summary> disclosures as native collapsible sections. OpenClaw tells the model about this option only when the current reply surface supports it. Other channels, including Telegram accounts without rich messages, flatten each disclosure to **Summary** followed by the visible body so no content is hidden or lost.

Adding or updating a channel formatter

1. Parse once with markdownToIR(...), passing channel-appropriate options (autolink, headingStyle, blockquotePrefix, tableMode).
2. Render with renderMarkdownWithMarkers(...) and a style-marker map (or custom style-range logic for transports like Signal).
3. Chunk with chunkMarkdownIR(...) or renderMarkdownIRChunksWithinLimit(...). The latter returns the measured rendered payload; use it directly instead of rendering the source again.
4. Wire the adapter to call the new chunker and renderer from the outbound send path.
5. Test with format tests plus an outbound delivery test if the channel chunks.

Common gotchas

• Slack angle-bracket tokens (<@U123>, <#C123>, <https://...>) must survive escaping; raw HTML still needs to be escaped safely.
• Telegram HTML requires escaping text outside tags to avoid broken markup.
• Signal style ranges use UTF-16 offsets, not code-point offsets.
• Preserve trailing newlines on fenced code blocks so the closing marker lands on its own line.
• Code-span parsing preserves all-space content. It removes one surrounding space from each end only when both are present and the content is not all spaces.
• Assistant-reply cleanup removes valid <final> markers outside Markdown code, including nested or stray markers, while keeping their enclosed answer text. Put literal <final>payload</final> examples in inline code or fenced code blocks so their tags are preserved.

Related