Developer docs

Mermaid diagrams in documents

A Mermaid diagram block stores the diagram as text and renders it as a picture. Because the source is the content, a proposal that changes a diagram shows a line-by-line diff of the code, just like any other edit.

Add a diagram

Type / in an empty line and pick Diagram (Mermaid) (or search "flowchart"), or use Insert → Diagram (Mermaid) in the toolbar.
Edit the source on the left; the preview on the right updates as you type. Press Done or Escape to go back to the document.
Click a diagram (or press Edit) to change it later.

mermaid

flowchart LR
  A[Draft] --> B{Review}
  B -->|Approved| C[Published]
  B -->|Changes| A

Any Mermaid diagram type works: flowchart, sequence, class, state, entity relationship, Gantt, pie, timeline and more. See the Mermaid syntax reference.

A syntax error shows a short message above the diagram and never changes your source. Diagrams follow the light or dark theme. For safety they render in strict mode: labels are plain text, with no HTML, scripts or click handlers.

Reviewing diagram changes

In Compare and proposal reviews an edited diagram is one changed block with a line diff of its source; unchanged diagrams render as pictures. Search finds diagram text such as node labels and participants.

Markdown, import and paste

A fenced block with the mermaid language becomes a diagram when you paste Markdown, import a .md file, or send Markdown through the API, CLI or MCP server. Markdown export and the API return the same fence, so diagrams round-trip with GitHub, GitLab and Obsidian.

markdown

```mermaid
sequenceDiagram
  Author->>Reviewer: Proposal
  Reviewer-->>Author: Approved
```

Export

Format	Diagram
PDF, Word (.docx), Google Docs	Rendered as an image in your browser
Markdown	`mermaid` code fence
Notion	Native Mermaid code block
HTML, Confluence	Source as a code block labeled "Mermaid diagram"

Shared, embedded and published pages render diagrams in the browser. Without JavaScript the source is shown instead.