Mermaid Diagram Tutorial: Flowcharts, Sequence Diagrams and Gantt Charts
Mermaid lets you describe a diagram in text. There are no boxes to drag and no image files to keep in sync: write a few lines inside your Markdown and the viewer draws the chart for you. Text diagrams are easy to edit and work well with version control, and they're supported by GitHub, GitLab, Notion and Moread.
Adding Mermaid to Markdown
Open a fenced code block with three backticks and set the language to mermaid:
```mermaid
flowchart LR
A[Start] --> B[Finish]
```
Put this in a .md file, open it in Moread and you'll see a left-to-right flowchart. Click Expand on the diagram to zoom in.
Flowcharts
The first line sets the direction: TD (top-down) or LR (left-right). Bracket styles define node shapes:
flowchart TD
A[Rectangle] --> B(Rounded)
B --> C{Decision}
C -->|Yes| D[[Subroutine]]
C -->|No| E((Circle))
-->is an arrow,---a plain line and-.->a dotted arrow.|text|labels an arrow, typically with a condition.- Node IDs (A, B, C) just need to be unique; the text in brackets is what's displayed.
Sequence diagrams
Ideal for showing how users and systems interact over time:
sequenceDiagram
participant U as User
participant S as Server
U->>S: Submit login
S-->>U: Return result
Note over U,S: All traffic uses HTTPS
->> is a solid arrow (request) and -->> a dashed arrow (response). Use Note over to annotate.
Gantt charts
Project schedules at a glance:
gantt
title Website redesign
dateFormat YYYY-MM-DD
section Design
Interviews :a1, 2025-01-06, 5d
UI design :after a1, 7d
section Build
Front end :2025-01-20, 10d
Test and launch :5d
Pie charts
pie title A typical day
"Work" : 8
"Sleep" : 7
"Reading" : 2
"Other" : 7
State diagrams
stateDiagram-v2
[*] --> Draft
Draft --> Review: Submit
Review --> Published: Approve
Review --> Draft: Reject
Published --> [*]
Troubleshooting
- The diagram doesn't appear: check that the code block language is
mermaidand that the first line names a diagram type (flowchart,sequenceDiagram, and so on). - Special characters in labels: wrap labels containing parentheses or colons in double quotes, e.g.
A["Price (incl. tax)"]. - Wrong direction keyword:
flowchartaccepts onlyTB,TD,BT,RLorLR. - When a diagram has an error, Moread keeps the source, shows the reason, and renders the rest of the document normally.
Tips
- Large charts are often easier to read with the
LRdirection. - A document can contain many diagrams; Moread draws up to 40 per file.
- Diagrams follow the Dark theme, and PDF export switches them to print-friendly light colors.
Want to see it live? On the Moread home page, click Diagrams · math · live code demo to open a sample document with Mermaid diagrams.