Diagrams
Draw flowcharts, sequence diagrams, and other Mermaid diagrams from text in a code fence.
Updated Nov 19, 2026
Write a Mermaid diagram in a code fence with the language mermaid, and the published page draws it. The diagram lives in your page as text, so it diffs and reviews like the rest of your docs.
flowchart LR
A[Write MDX] --> B[Push to GitHub]
B --> C{Build passes?}
C -->|Yes| D[Site is live]
C -->|No| E[Previous version stays up]```mermaid
flowchart LR
A[Write MDX] --> B[Push to GitHub]
B --> C{Build passes?}
C -->|Yes| D[Site is live]
C -->|No| E[Previous version stays up]
```
Diagrams follow the reader's light or dark theme and redraw when they switch.
Diagram types
Any diagram Mermaid supports works, for example:
| Diagram | First line |
|---|---|
| Flowchart | flowchart LR or graph TD |
| Sequence diagram | sequenceDiagram |
| Class diagram | classDiagram |
| State diagram | stateDiagram-v2 |
| Entity relationship | erDiagram |
| Gantt chart | gantt |
| Pie chart | pie |
sequenceDiagram
participant App
participant API
App->>API: POST /tokens
API-->>App: 201 Created```mermaid
sequenceDiagram
participant App
participant API
App->>API: POST /tokens
API-->>App: 201 Created
```
In tabs and code groups
A diagram works anywhere a code block does, including inside Tabs and Code groups. In a code group, the label after mermaid names the tab.
<CodeGroup>
```mermaid Flow
flowchart LR
Request --> Response
```
```bash curl
curl https://api.acme.com/health
```
</CodeGroup>
When a diagram has an error
If Mermaid can't read a diagram, the page shows its source as a code block with a short note naming the error, such as "Parse error on line 2". The rest of the page is unaffected. Fix the diagram and publish again.
Readers without JavaScript, and AI tools reading your page as Markdown or through llms.txt, get the diagram's source.
Security
Diagrams are drawn in the reader's browser with Mermaid's strict security level: labels can't contain scripts, and click actions in diagrams are turned off.
In the visual editor
A Mermaid block stays a code block you type into, with the diagram drawn underneath. The drawing updates a moment after you stop typing, and shows the error if the diagram has one. To start one, insert a Code block and pick Mermaid from the language picker.