{"topic":"document-format","title":"Falconer document format","description":"Markdown syntax, inline references, math, tables, media and content preservation.","content":"# Falconer document format\n\nFalconer document content uses Markdown with supported rich components and dedicated editor nodes.\nUse headings, paragraphs, bold, italic, strikethrough, links, lists, task lists, blockquotes and fenced code blocks with language names. Separate block content with blank lines.\nPreserve the existing structure, reference identifiers and special syntax when editing. The read response is the source for exact text matches; parsing and saving may normalize equivalent Markdown forms.\n\n## Inline references\n\nFalconer stores references as `![f>][referenceId]`. They render as reference pills or citations in Falconer documents and chat.\nCopy the identifier exactly from the returned reference or document metadata. Falcon's internal `document_search` results expose `referenceId` for citations and, for Falconer-native documents, `documentId` for fetching or editing. The public document API, hosted MCP, local MCP and CLI expose a native document UUID as `id` in document search and read responses; use that UUID to reference the native document. Attachment metadata exposes `referenceId` for the uploaded file.\nIdentifiers are opaque, have no fixed length, and can identify documents, source excerpts, people, folders or uploaded files. Never invent, shorten or infer an identifier from its shape.\n\nExample: `The rollout starts on Monday. ![f>][exact-reference-id]`\n\nOlder content can use `![f>][display text][referenceId]`. Preserve the reference identity and placement when editing. The editor accepts this legacy form and normalizes it to `![f>][referenceId]` when serializing.\nReference syntax inside inline code or fenced code remains literal.\nUse normal Markdown links, `[label](url)`, for external URLs. A reply in an external host should use the host's supported links or citation format; Falconer reference tokens are for content rendered in Falconer. Follow the calling surface's citation policy for placement and frequency.\n\n## Math\n\nAuthor inline math as `<span data-type=\"inline-math\" data-latex=\"...\"></span>` and block math as `<div data-type=\"block-math\" data-latex=\"...\"></div>`.\nThe `data-latex` attribute contains LaTeX with HTML attribute escaping where needed. These are dedicated math nodes, so they do not belong inside an `<Html>` embed or a code block.\nThe parser also accepts dollar-delimited math, including `$...$`, `$$...$$` and block `$$$...$$$`, and normalizes it to HTML math nodes on serialization. When editing, copy matching text exactly from the read response and use HTML math nodes for new formulas.\n\nInline example: `Energy is <span data-type=\"inline-math\" data-latex=\"E=mc^2\"></span>.`\nBlock example: `<div data-type=\"block-math\" data-latex=\"\\sum_{i=1}^{n} x_i\"></div>`\n\nWhen content is passed in JSON tool arguments, escape each LaTeX backslash as a double backslash. To write `\\nabla`, the JSON string contains `\\\\nabla`.\n\n## Tables\n\nUse GitHub-flavored Markdown tables by default.\nTo color a cell, use an HTML `<table>` with `data-bg-color` on its `<td>` or `<th>` elements. Available colors are `red`, `orange`, `yellow`, `green`, `blue` and `purple`. Only add cell colors when requested.\nThese native table tags are a supported exception to the raw HTML embed rule.\nMarkdown reads and exports can normalize a table to pipe syntax, which does not encode cell colors.\n\n`<table><tr><th>Status</th><th>Task</th></tr><tr><td data-bg-color=\"green\">Done</td><td>Deploy</td></tr></table>`\n\n## Images, videos, audio and file attachments\n\nFor uploaded media and files, call the surface's media upload operation first and insert the returned Markdown snippet into the document. Do not persist temporary download URLs returned for attachments.\nUse `![alt](url)` for images. For video, use `<video src=\"https://example.com/demo.mp4\" title=\"Product demo\" controls></video>`, and for audio, `<audio src=\"https://example.com/voiceover.mp3\" title=\"Launch voiceover\" controls></audio>`. The title is optional; keep controls. Videos and audio render as native document content and do not belong in `<Html>` embeds.\nOther files (PDF, Office documents, text, Markdown, HTML, CSV, TSV, ZIP, JSON and source code) upload as attachments. Insert the returned `![f>][referenceId]` snippet where the file belongs; it renders as a file pill and the document read response lists the file under attachments.\n\n## Components and styled content\n\nRead the `document-components` topic before authoring callouts, accordions, tabs, columns, cards or steps.\nRead `html-components` before styled headings, paragraphs, images, inline spans, section containers or raw HTML embeds. Availability of styled content and embeds can depend on the organization or calling surface.\nDedicated math nodes and native HTML table tags are supported document syntax, even though general bare HTML is not. Arbitrary HTML, CSS, SVG and scripts belong in a complete `<Html>...</Html>` embed where available.\nRead `diagrams` before authoring Mermaid or D2 code blocks. External chat hosts may not render Falconer components or diagrams; use them in the Falconer document content rather than assuming the host supports them."}