openclaw/docs/concepts/markdown-formatting.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Markdown formatting pipeline for outbound channels"
read_when:
  - You are changing markdown formatting or chunking for outbound channels
  - You are adding a new channel formatter or style mapping
  - You are debugging formatting regressions across channels
title: "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.

Examples of shared IR renderers:

| Channel  | Renderer                                                                             | Notes                                                                                    |
| -------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| Matrix   | HTML tags, including native tables                                                   | Automatic replies, direct sends, and media captions use the same formatter               |
| Signal   | plain text + `text-style` ranges                                                     | Links render as `label (url)` when the label differs from the URL                        |
| Slack    | mrkdwn tokens (`*bold*`, `_italic_`, `` `code` ``, code fences)                      | Links become `<url\|label>`; autolink disabled during parse to avoid double-linking      |
| Telegram | HTML tags (`<b>`, `<i>`, `<s>`, `<code>`, `<pre><code>`, `<a href>`, `<tg-spoiler>`) | Also supports rich-message tables and headings (`<h1>`-`<h6>`) when `richMessages` is on |
| WhatsApp | WhatsApp style markers                                                               | Uses shared IR; styled chunks are measured after rendering                               |

## IR example

Input Markdown:

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

IR (schematic):

```json
{
  "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:

| Mode      | Behavior                                                                             |
| --------- | ------------------------------------------------------------------------------------ |
| `code`    | Render as an aligned ASCII table inside a code block (fallback default)              |
| `bullets` | Convert each row into `label: value` bullet points                                   |
| `block`   | Keep native tables where the transport supports them; falls back to `code` otherwise |
| `off`     | Disable table parsing; raw table text passes through unchanged                       |

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`.

```yaml
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.
- Inline styles never split across chunks; the renderer reopens an open
  style at the start of the next chunk.

See [Streaming and chunking](/concepts/streaming) 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.

## Related

<CardGroup cols={2}>
  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
    Outbound streaming behavior, chunk boundaries, and channel-specific delivery.
  </Card>
  <Card title="System prompt" href="/concepts/system-prompt" icon="message-lines">
    What the model sees before the conversation, including injected workspace files.
  </Card>
</CardGroup>