Mermaid turns plain text into diagrams. Start every diagram with its type, then add the smallest useful set of nodes and relationships.
See the syntax become a diagram
Start every diagram correctly
Mermaid source starts with a diagram declaration. Comments begin with %% and a config directive can control the renderer before that declaration.
%%{init: { "theme": "base" }}%%
%% This line is a comment
flowchart LR
A --> B- Use one diagram type per code block.
- Indentation improves readability, while declarations and keywords define the syntax.
- Use frontmatter, directives, themes, layout settings, and accessibility metadata for renderer-level configuration.
- Quote labels when punctuation could be parsed as Mermaid syntax; quote the word end in flowcharts and sequences.
Flowcharts
Use flowcharts for decisions, processes, system overviews, and anything that needs arrows.
flowchart LR
A[Visitor] --> B{Signed in?}
B -->|Yes| C[Workspace]
B -->|No| D[Sign in]
D --> C- Directions: TB, TD, BT, LR, and RL.
- Node shapes: [rectangle], (rounded), {diamond}, and ((circle)).
- Link forms include -->, --- , -.->, ==>, and -->|label|.
- Use subgraph / end, click, linkStyle, classDef, class, and :::class for grouping, interaction, and presentation.
Sequence diagrams
Make requests and responsibilities explicit between people, services, and systems.
sequenceDiagram
participant App
participant API
participant DB
App->>API: Save diagram
API->>DB: Insert source
DB-->>API: Saved
API-->>App: 201 Created- Use ->> for a solid message and -->> for a response; dotted and open-arrow forms are also available.
- Add Note right of API: text for inline context.
- Use alt, opt, loop, par, critical, break, rect, and background blocks for control flow.
- autonumber, activate/deactivate, create, and destroy make ordering and lifetimes explicit.
Class and state diagrams
Use classes for structure and states for lifecycles.
classDiagram
class Diagram {
+String source
+render()
}
class Workspace {
+save()
}
Workspace "1" --> "many" Diagram
stateDiagram-v2
[*] --> Draft
Draft --> Published: submit
Published --> Archived: retire
Archived --> [*]- Visibility markers: + public, - private, # protected, and ~ package.
- Class relations include inheritance, composition, aggregation, dependency, and realization; use multiplicities in quotes.
- In state diagrams, [*] marks initial/final states; use composite states, notes, forks, joins, and choices for complex lifecycles.
Styling without losing clarity
Keep styles limited to meaning: highlight the important path, exception, or final state.
flowchart LR
A[Draft] --> B[Review] --> C[Published]
classDef focus fill:#eeedff,stroke:#635bff,color:#35306f
class C focus
linkStyle 1 stroke:#635bff,stroke-width:3px- classDef declares a reusable appearance.
- class attaches the appearance to one or more node IDs.
- Quote labels that contain punctuation if the parser needs help.
Data, planning, and metric diagrams
Use Mermaid’s compact declarations for entity relationships, schedules, proportions, journeys, timelines, and simple charts.
erDiagram
CUSTOMER ||--o{ ORDER : places
gantt
title Release
dateFormat YYYY-MM-DD
Build :a1, 2026-08-01, 3d
pie title Traffic
"Direct" : 65
"Referral" : 35
timeline
2026 : Launch
: Iterate- erDiagram covers entities, attributes, cardinality, identifying relationships, and relationship labels.
- gantt supports title, dateFormat, sections, tasks, milestones, dependencies, critical work, and completion states.
- journey, timeline, quadrantChart, xychart-beta, pie, radar, and sankey-beta cover reporting views.
Specialized diagram families
Use the dedicated declaration for planning, version-control, architecture, and engineering-specific views.
gitGraph
commit id: "base"
branch feature
checkout feature
commit id: "work"
mindmap
root((Diagram))
Docs
Architecture
kanban
Todo
[Plan guide]
Done
[Publish]- gitGraph models commits, branches, checkout, merge, cherry-pick, tags, and custom commit types.
- mindmap, kanban, treemap, block, swimlane, treeview, and event modelling cover planning and structured content.
- C4, architecture, packet, requirement, ZenUML, Venn, Ishikawa, Wardley, and Cynefin have dedicated grammar and reference pages.
Keep it useful
Three working rules
- Prefer a short node label over a full sentence.
- Use LR for a compact process; use TB when labels are longer.
- Preview often: small syntax errors are easiest to fix near the line that introduced them.
Official sources
Further reading
Use the official references for version-specific details, niche syntax, and advanced renderer options.