Mermaid diagram syntax
Mermaid diagrams are architecture assets. Use them when a relationship, sequence, lifecycle, or map is clearer as structured text than as prose or a static image.
Prefer the smallest diagram type that explains the idea. Keep diagrams local, reviewable, and close to the page that depends on them.
Load Mermaid on the page#
Mermaid JavaScript is not loaded globally. Any page that contains a Mermaid fence or the
mermaid shortcode must opt in through its front matter:
mermaid: truelayouts/_default/baseof.html reads this page parameter and imports Mermaid only for that
page. Without it, the diagram source remains in the rendered HTML but is not converted to an
SVG diagram.
Syntax inventory#
The source of truth for syntax is Mermaid’s Diagram Syntax documentation.
| Diagram type | Use when | Mermaid syntax |
|---|---|---|
| Flowchart | Showing decisions, steps, branching, or system movement | Flowchart |
| Swimlanes diagram | Showing work split across actors, systems, or responsibilities | Swimlanes Diagram |
| Sequence diagram | Showing messages or calls over time | Sequence Diagram |
| Class diagram | Showing object models, type relationships, or interface structure | Class Diagram |
| State diagram | Showing lifecycle states and transitions | State Diagram |
| Entity relationship diagram | Showing data entities and relationships | Entity Relationship Diagram |
| User journey | Showing user stages, tasks, and satisfaction | User Journey |
| Gantt | Showing schedules, phases, or delivery windows | Gantt |
| Pie chart | Showing simple part-to-whole comparisons | Pie Chart |
| Quadrant chart | Plotting items across two dimensions | Quadrant Chart |
| Requirement diagram | Showing requirements and relationships between them | Requirement Diagram |
| GitGraph diagram | Showing Git branches, commits, merges, and release movement | GitGraph (Git) Diagram |
| C4 diagram | Showing system context, containers, components, and deployment views | C4 Diagram |
| Mindmap | Showing hierarchical ideas or notes | Mindmaps |
| Timeline | Showing events in chronological order | Timeline |
| ZenUML | Showing sequence-style interaction with ZenUML syntax | ZenUML |
| Sankey | Showing flows and quantities between stages | Sankey |
| XY chart | Showing simple charted values on x and y axes | XY Chart |
| Block diagram | Showing labelled blocks and spatial relationships | Block Diagram |
| Packet | Showing packet or frame structure | Packet |
| Kanban | Showing cards grouped by workflow status | Kanban |
| Architecture | Showing architecture services, groups, and edges | Architecture |
| Radar | Showing maturity, capability, or assessment scores | Radar |
| Event modelling | Showing events, commands, views, and user interactions over time | Event Modelling |
| Treemap | Showing hierarchical quantities by area | Treemap |
| Venn | Showing overlaps between sets | Venn |
| Ishikawa | Showing cause-and-effect analysis | Ishikawa |
| Wardley | Showing value chains and evolution | Wardley |
| Cynefin | Sorting situations by decision-making domain | Cynefin |
| TreeView | Showing file trees, hierarchies, or nested structures | TreeView |
| Other examples | Checking syntax patterns that do not fit one family cleanly | Other Examples |
Use rules#
- Use Mermaid when the diagram benefits from version control, diffs, and local review.
- Use a static image when visual fidelity matters more than source readability.
- Keep labels short. If the label needs a paragraph, the diagram is carrying too much meaning.
- Prefer one diagram per concept. Split large diagrams before they become maps of everything.
- Keep diagram source in the Markdown page unless the same source is reused by multiple pages.