documents

# Documents A document is a rich-text page mixing prose with embedded saved questions. `document_write` takes **Metabase-flavored Markdown**: CommonMark plus tokens. Charts must exist first (`question_write`), embedded by id. ``` document_write {"method": "create", "name": "Weekly report", "content_markdown": "# Weekly report\n\nOrders trended up this week.\n\n{% card id=118 %}\n"} ``` **CommonMark subset:** headings, paragraphs, bold/italic/inline code, links (bare URLs autolink), lists, blockquotes, fenced code, horizontal rules, images. **No tables, strikethrough, or task lists** — the editor has no nodes for them; show tabular data by embedding a table-display question. ## Tokens - **Card embed** (block, own line): `{% card id=118 %}` or `{% card id=118 name="Revenue by region" %}` (`name` overrides the title). The id must be a saved question you can read; an unresolvable id fails the write. Height is assigned for you. - **Entity link** (inline chip): `{% entity id="42" model="dashboard" %}` — id quoted; `model` ∈ `card`, `dataset`, `metric`, `dashboard`, `collection`, `table`, `database`, `document` (`user` parses but renders without a working link). ## Layout containers (`:::` fences) `::: <name> {attrs}` on its own line opens a container; a bare `:::` closes the **innermost** open one (never `::: end`) — every opener needs its own closer, in order. - `::: flex {columns=[60,40]}` — a row of 1–3 cells (percent widths); a cell is a card embed or a `::: supporting` block. Never nest `flex` in `flex`. - `::: supporting` — a prose cell (paragraphs, headings, lists) inside a flex row. - `::: resize {height=442 minHeight=280}` — wraps exactly one card embed or flex row to pin its pixel height. Prose beside a chart: ```markdown ::: flex {columns=[60,40]} ::: supporting ### What happened Revenue climbed through the quarter, led by the Gadget category. ::: {% card id=118 %} ::: ``` (First `:::` closes `supporting`, last closes `flex`.) To pin the row's height, wrap it in `::: resize {height=400}` … `:::`. ## Card clones A card the document doesn't already own is **cloned into it** on write and its id rewritten in the stored body — the markdown stored is not the markdown you sent, so always take the returned `content_markdown` as current, and edit against that, never your own earlier text. The clone is what renders: to change an embedded chart (display, settings, query), `question_write` the **clone id** shown in `content_markdown`; the master card does nothing for the document. E.g. you embedded 148, the body now reads `{% card id=155 %}` — `question_write {"method": "update", "id": 155, "display": "row"}` changes the document, updating 148 does not. ## Updating Pass `id` and exactly **one** of: - `edits: [{old_str, new_str, replace_all?}]` — the default. Each `old_str` must match the **current server-side** markdown exactly once: 0 matches = the document changed since you read it (copy from the returned `content_markdown`); >1 = extend the snippet or set `replace_all: true`. Blocks keep their ids, so comment anchors survive. - `content_markdown` — full rewrite; every block is re-created, so **every comment thread on the body is orphaned** (listed in the response's `orphaned_comment_threads`). Only for restructuring; tell the user first. - `edits: []` — metadata only (`name`, `collection_id`, `collection_position`, `archived`), body untouched. Writes are last-write-wins; a stale `old_str` failing to match is the only staleness signal. **What `edits` can do:** `new_str` is parsed as Markdown, the same grammar as `content_markdown`. Inline syntax such as `**bold**` or `*em*` formats, a blank line (`\n\n`) splits a paragraph, and a `new_str` that replaces a whole block with `- item` lines, a fence, or a `:::` container turns it into that block (listed in `changed_blocks`). Inside a code span or code block the replacement stays code. So edits cover rewording, formatting, and restructuring a block; `content_markdown` is only for rewriting the whole body. Add a paragraph — extend the end of the block before it: ``` "edits": [{"old_str": "led by the Gadget category.", "new_str": "led by the Gadget category.\n\nGizmos were flat for the third quarter running."}] ``` Edit one bullet - match its text only, never the `- ` marker, so the edit stays inside that item: ``` "edits": [{"old_str": "Churn fell to 4%", "new_str": "Churn fell to 3.8%"}] ``` ## Comments `get_content {"type": "document", "id": 12, "include": ["comments"]}` returns threads grouped by anchored block, each with `anchor: {start, end, text}` — the exact character slice of the returned `content_markdown` — and `thread` messages (`id`, `creator`, `text`, `is_resolved`, `created_at`). A thread whose block was rewritten or deleted appears under `orphaned_comments`: the discussion still exists but points at no text, and only the UI can re-anchor it. MCP can read comments but not reply, resolve, or re-anchor — tell the user when a thread needs that. ## Don't - Don't `question_write` the master card to change an embedded chart — a no-op for the document; edit the clone id. - Don't put Markdown syntax in `new_str` that you mean literally - it is parsed; escape it (`\*`). - Don't include the `- ` marker in a bullet edit - match the item's text only. - Don't full-rewrite for a small change — every comment thread is orphaned, irreversibly. - Don't write tables, strikethrough, or task lists — no document representation. ## To confirm `get_content {"type": "document", "id": 12}` returns the stored `content_markdown` (clone ids included); add `"include": ["layout"]` for the block outline, `["comments"]` for anchors. Rendering in the editor has no API check.