Mermaid Diagram Guide

Mermaid is a text-based diagram syntax: a ```mermaid fenced code block is rendered into flowcharts, sequence diagrams, Gantt charts and more. You describe the diagram in a few lines of text — no drawing tool required.

```mermaid
graph TD
    A[Write Mermaid code] --> B[Editor renders it live]
    B --> C[Copy into docs or export as PDF]
```

Three rules of thumb: the code fence language must be `mermaid`; start each statement at the beginning of a line (avoid mixing tabs and spaces); the diagram declaration such as `graph TD` must be the first line.

`graph TD` declares a top-down flowchart, `graph LR` a left-to-right one. Nodes are named with any identifier and connected with `-->` arrows:

```mermaid
graph LR
    A[Draft] --> B[Edit]
    B --> C{Happy?}
    C -->|Yes| D[Publish]
    C -->|No| B
```

Swap `TD` for `LR`, `BT` or `RL` to get the four possible directions. A node identifier appears only once — repeat it in edges to express branches and loops.

Different brackets produce different node shapes, letting you distinguish steps, decisions and endpoints at a glance:

```mermaid
graph TD
    A[Rectangle: normal step]
    B(Rounded: start or end)
    C{Diamond: decision}
    D((Circle: connector))
    E([Stadium: begin or finish])
    F[(Cylinder: database)]
    A --> B --> C
    C --> D
    C --> E
    D --> F
```

If the label contains parentheses, quotes or other special characters, wrap it in quotes: `A["text (with parens)"]`.

Edges come in solid, dotted and thick variants, and can carry a text label:

```mermaid
graph LR
    A --> B[Solid arrow]
    B -.- C[Dotted, no arrow]
    C -.-> D[Dotted arrow]
    D ==> E[Thick arrow]
    E -- Labeled edge --> F[Target]
    F -->|Alternative syntax| G[Target]
```

Longer arrows add spacing: `--->` is longer than `-->`. The two label syntaxes — `-- text -->` and `-->|text|` — are equivalent; pick one and stay consistent.

`subgraph ... end` groups related nodes into a box — useful for modules or actors — and edges between groups show how they interact:

```mermaid
graph TB
    subgraph Frontend
        P[Editor page] --> V[Live preview]
    end
    subgraph Static hosting
        S[Static assets] --> H[HTML documents]
    end
    P --> S
    V --> H
```

A subgraph can also set its own layout direction with `direction LR` on the line right after `subgraph Name`.

`sequenceDiagram` starts a sequence diagram, `participant` declares an actor, `->>` draws a solid request arrow and `-->>` a dashed response. Adding `autonumber` numbers every message automatically:

```mermaid
sequenceDiagram
    autonumber
    participant U as User
    participant E as Editor
    participant S as Export service
    U->>E: Click export PDF
    E->>S: Send document content
    S-->>E: Return PDF file
    E-->>U: Trigger browser download
```

Participants appear left to right in declaration order; the name after `as` is the display name — omit it to show the identifier itself.

`activate`/`deactivate` mark when a participant is busy (the rectangles on lifelines). The shorthand is a trailing `+` (activate) or `-` (deactivate) on the message arrow:

```mermaid
sequenceDiagram
    participant U as User
    participant A as App
    participant D as Database
    U->>+A: Request document list
    A->>+D: Query data
    D-->>-A: Return rows
    A-->>-U: Render the list
```

`+` activates the receiving participant; pair each `+` with a `-` to show the call stack entering and leaving.

`note` adds annotations, while `loop`, `alt/else`, `opt` and `par` express loops, branches and parallel regions:

```mermaid
sequenceDiagram
    participant U as User
    participant S as Search service
    U->>S: Type a keyword
    loop Debounce window
        S->>S: Merge requests for 300ms
    end
    alt Results found
        S-->>U: Return suggestions
    else No results
        S-->>U: Return empty list
    end
    Note over U,S: Interaction complete
```

Use `note left of` / `note right of` to place a note beside one participant, or `note over A,B` to span several.

`classDiagram` describes classes, members and relationships. `+`, `-` and `#` mean public, private and protected; `-->` is a solid association, `..>` a dashed dependency, `<|--` inheritance and `<|..`>` implementation:

```mermaid
classDiagram
    class Editor {
        +String content
        +render() void
        +exportTo(format) File
        -autoSave() void
    }
    class Exporter {
        +toPDF() File
        +toHTML() File
    }
    class Renderer {
        <<interface>>
        +render() void
    }
    Editor --> Exporter : delegates export
    Editor ..> Renderer : depends on
    Renderer <|.. VditorRenderer : implements
```

Text after `:` on a relationship is a free-form label; stereotypes such as `<<interface>>` go on the first line of the member list.

`stateDiagram-v2` models states and transitions. `[*]` marks the initial and final states, and the text after `:` on a transition names the triggering event:

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Published : approve
    Review --> Draft : request changes
    Published --> [*]
```

Complex states can nest: `state Name { ... }` defines a sub-state machine:

```mermaid
stateDiagram-v2
    [*] --> Editing
    state Editing {
        [*] --> Typing
        Typing --> AutoSaving
        AutoSaving --> Typing
    }
    Editing --> Saved : manual save
    Saved --> [*]
```

`erDiagram` describes database entity relationships. Entity names should use uppercase letters and underscores; inside braces, list one `type name key` per line; relationship crow's-foot symbols express cardinality:

```mermaid
erDiagram
    USER ||--o{ DOCUMENT : creates
    DOCUMENT ||--|{ TAG : labeled with
    USER {
        string id PK
        string name
        string email
    }
    DOCUMENT {
        string id PK
        string user_id FK
        string title
        datetime created_at
    }
```

Reading the symbols: `||` exactly one, `o|` zero or one, `} {` many. So `||--o{` is "one to zero-or-many". `PK` and `FK` mark primary and foreign keys.

`gantt` lays out a schedule from dates and durations. `dateFormat` sets the input date format and `axisFormat` the axis label format. Write tasks as `name :status, id, start, duration` and chain them with `after id`:

```mermaid
gantt
    title Docs revamp plan
    dateFormat YYYY-MM-DD
    axisFormat %m-%d
    section Research
    Competitive analysis :done, t1, 2026-01-05, 3d
    User interviews :active, t2, after t1, 4d
    section Writing
    First draft :t3, after t2, 5d
    Review and revisions :t4, after t3, 3d
    section Launch
    Release :t5, after t4, 1d
    crit Canary rollout :crit, t6, after t5, 2d
```

Status flags: `done` is finished, `active` in progress, `crit` on the critical path. Flags combine, e.g. `:done,crit,`.

`pie` renders a proportion chart. Put the title after `pie title`, then one `"Label" : value` per line:

```mermaid
pie title Traffic sources for content pages
    "Search engines" : 62
    "Direct visits" : 23
    "Referrals" : 10
    "Social" : 5
```

Values need not be percentages — Mermaid computes each share of the total automatically. Always wrap labels in double quotes.

Paste any example on this page into the [MarkdownAssistant online editor](/en/) and the preview pane renders the diagram instantly — edit the code and the chart redraws as you type. Diagrams mix freely with prose, formulas and tables:

```mermaid
graph LR
    A[Markdown text] --> B{Has diagrams?}
    B -->|Yes| C[Mermaid rendering]
    B -->|No| D[Plain layout]
    C --> E[Export PDF / HTML]
    D --> E
```

Diagrams are embedded as-is when you export to PDF, and their color scheme follows the light/dark theme automatically.

**Diagram not rendering, error panel shown?** It is almost always syntax: check that the diagram declaration is on the first line, brackets are balanced, and lines do not start with stray spaces. If a label contains characters like `( ) { } [ ]`, wrap it in quotes: `A["text (with parens)"]`.

**Diagram too dense?** Changing the flowchart direction (TD/LR) usually helps more than tweaking spacing; adding `autonumber` to a sequence diagram makes steps easy to reference in prose.

**Chart squeezed by the container?** Rendered diagrams scale to fit the preview width; export or open the preview fullscreen to see them at full size.

```mermaid
graph TD
    A["Type Mermaid code"] --> B{"Syntax valid?"}
    B -->|Yes| C["Diagram renders"]
    B -->|No| D["Read the error panel"]
    D --> A
```