Mermaid syntax primer: 7 diagram types you can embed in Markdown

“Markdown is great for documents but you can’t draw diagrams in it” — except now you can. Mermaid turns code blocks into rendered SVG diagrams (flowcharts, sequence diagrams, Gantt charts, etc.). It works on GitHub, Notion, Obsidian, ChatGPT, Claude, and most modern documentation tools, making it the de-facto way to embed diagrams in Markdown.

What is Mermaid

Mermaid is a JavaScript library that renders text into SVG diagrams. The pattern:

```mermaid
flowchart LR
    A[Start] --> B{Condition}
    B -->|Yes| C[Process]
    B -->|No| D[End]
```

A Mermaid-aware renderer turns this into a flowchart with arrows.

Common environments that render Mermaid:

• GitHub (READMEs, Issues, PR comments)
• GitLab
• Notion
• Obsidian
• VS Code (via extension)
• ChatGPT, Claude (in AI chat output)
• Documentation generators (Docusaurus, MkDocs, VuePress, etc.)

Diagram types Mermaid supports

Diagram	Keyword	Typical use
Flowchart	flowchart / graph	Process flows, decision branches
Sequence	sequenceDiagram	API calls, method invocations
Gantt	gantt	Project schedules
Class	classDiagram	OOP design, UML
State	stateDiagram-v2	UI state, lifecycles
ER	erDiagram	Database design
Pie	pie	Percentage breakdowns

1. Flowchart

The most fundamental and most-used.

```mermaid
flowchart TD
    A[User input] --> B{Validation}
    B -->|OK| C[Save to DB]
    B -->|NG| D[Show error]
    C --> E[Done]
    D --> A
```

Notes:

• TD = Top-Down, LR = Left-Right
• Node shapes: [rect], (rounded), {diamond (decision)}, ((circle))
• Arrows: --> normal, -.-> dashed, ==> thick, -->|label| labeled

2. Sequence diagram

For API exchanges and call sequences.

```mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: User row
    API-->>Client: JWT token
    Client->>API: GET /profile (Bearer JWT)
    API-->>Client: Profile
```

Notes:

• ->> synchronous call, -->> reply, -) async
• Participants are added in the order they appear (left to right)
• Note over A,B: text adds a note

3. Gantt chart

Project timelines.

```mermaid
gantt
    title Project schedule
    dateFormat YYYY-MM-DD
    section Design
    Requirements :a1, 2026-04-01, 7d
    Architecture :after a1, 14d
    section Implementation
    Frontend :2026-04-22, 21d
    Backend  :2026-04-22, 28d
    section Test
    Integration :2026-05-20, 7d
```

Notes:

• dateFormat defines the input date format
• after a1 chains tasks
• section groups tasks into phases

4. ER diagram

Database table relationships.

```mermaid
erDiagram
    USER ||--o{ POST : creates
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes
    USER {
        int id PK
        string email
        string name
    }
    POST {
        int id PK
        int user_id FK
        string title
        text body
    }
```

Notes:

• Relation marks: ||--o{ is “one to many”, ||--|| is “one to one”
• Attributes can include PK (primary key) and FK (foreign key)

5. State diagram

UI state management or workflows.

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Submitting: Click submit
    Submitting --> Success: 200 OK
    Submitting --> Failed: Error
    Failed --> Idle: Retry
    Success --> [*]
```

Notes:

• [*] marks start and end states
• state --> state: event adds a trigger label

6. Class diagram

UML-style class relationships.

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        +sleep()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog
```

7. Pie chart

Quick percentage breakdowns.

```mermaid
pie title Language usage share
    "JavaScript" : 45
    "TypeScript" : 30
    "Python" : 15
    "Go" : 10
```

Common gotchas

1. Renderer version differences

Mermaid moves quickly; new features (the v2 in stateDiagram-v2, C4 diagrams, etc.) depend on the renderer’s bundled version. GitHub stays relatively current, but tools like Notion sometimes lag.

2. Wide text in Japanese / CJK

Long CJK strings inside a node sometimes don’t fit cleanly. Use <br/> for explicit line breaks, or shorten the label:

A[Cart updates<br/>after add]

3. Spaces in arrow labels

Quote arrow labels that contain spaces:

A -->|"with space"| B

4. Validate before pushing

Mermaid Live Editor (mermaid.live) is the easiest way to confirm syntax before pasting into a GitHub PR or Notion page. Bad syntax can break rendering for the whole document section.

Mermaid vs alternatives

Use case	Mermaid	Dedicated tool
Quick README diagrams	✅ Mermaid	drawio (PNG)
Pixel-perfect layout	△ tedious	✅ Figma / drawio
Version-controlled (diffable)	✅ Mermaid (text)	❌ binary, no diff
Real-time collaboration	✅ via PRs	✅ Figma
Complex UML	△ hits limits	✅ PlantUML / Lucidchart

”Diagrams as text, committed alongside code” is Mermaid’s killer feature — the diff-friendly nature beats binary formats for engineering teams.

Summary

• Mermaid embeds diagrams as text into Markdown
• Supports flowchart, sequence, Gantt, ER, state, class, and pie
• Native rendering on GitHub, Notion, Obsidian, and most AI chats
• Diagrams become version-controllable

To preview Markdown with Mermaid blocks while drafting, the Markdown preview tool on this site shows the surrounding Markdown — Mermaid rendering itself depends on the destination (GitHub, Notion, etc.), so verify the final view there.