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 mermaid and 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: flowchart accepts only TB, TD, BT, RL or LR.
  • 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 LR direction.
  • 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.