Mermaid diagrams in Markdown

Mermaid is a JavaScript library with its own small text syntax for diagrams. You write what the diagram contains — the nodes, the arrows, the participants — and the layout engine decides where everything goes. There is no dragging and no coordinates.

That trade is the whole point. You give up fine control over positioning and get a diagram that is a few lines of text: reviewable in a pull request, editable by anyone, and diffable when it changes. It covers flowcharts, sequence diagrams, class and entity-relationship diagrams, state machines, Gantt charts, pie charts, user journeys, mind maps, timelines and more. This page uses Mermaid version 11, which is what GitHub and this viewer run.

There is no separate Mermaid syntax inside Markdown. You write an ordinary fenced code block and tag it mermaid. A renderer that understands the tag draws a diagram; one that does not shows the code, which is at least a readable fallback.

The first line inside the fence declares the diagram type — flowchart, sequenceDiagram, gantt, pie, stateDiagram-v2, erDiagram, classDiagram, mindmap, timeline. Everything after it follows that type's grammar, and the grammars differ, which is the source of most confusion when copying between diagrams. Indentation inside a Mermaid block is for your eyes only, apart from a few types such as mindmap where it defines the structure.

```mermaid
flowchart LR
    A[Write] --> B[Commit] --> C[Review]
```

flowchart LR
    A[Write] --> B[Commit] --> C[Review]

The most used type by a wide margin. Declare flowchart and a direction: TD or TB for top-down, LR for left-to-right, also RL and BT. Then list the connections.

A node is an id followed by a shape: square brackets for a rectangle, curly braces for a decision diamond, round brackets for a rounded box, double round brackets for a circle. Define a node's label once — after that, the bare id is enough. Arrows are --> for solid, -.-> for dotted, ==> for thick, and --- for a line with no arrowhead. Text on an arrow goes between pipes after it.

```mermaid
flowchart TD
    A[Push to main] --> B{Tests pass?}
    B -->|yes| C[Deploy to staging]
    B -->|no| D[Open an issue]
    C --> E{Smoke test OK?}
    E -->|yes| F[Promote to production]
    E -->|no| D
```

flowchart TD
    A[Push to main] --> B{Tests pass?}
    B -->|yes| C[Deploy to staging]
    B -->|no| D[Open an issue]
    C --> E{Smoke test OK?}
    E -->|yes| F[Promote to production]
    E -->|no| D

For anything that happens in order between parties: an API handshake, a login flow, a message passing through a queue. Declare sequenceDiagram, then optionally name your participants so they appear in the order you want rather than the order they are first mentioned.

Arrow forms carry meaning here. ->> is a solid arrow for a call, -->> a dashed one for a reply, and appending x gives a cross for a failed or lost message. activate and deactivate — or a + and - on the arrows — draw the lifeline bars. Note over A,B adds an annotation, and loop, alt, opt and par blocks wrap a group of messages, each closed with end.

```mermaid
sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /orders
    A->>D: INSERT order
    D-->>A: order id
    alt payment authorised
        A-->>U: 201 Created
    else declined
        A-->>U: 402 Payment Required
    end
```

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /orders
    A->>D: INSERT order
    D-->>A: order id
    alt payment authorised
        A-->>U: 201 Created
    else declined
        A-->>U: 402 Payment Required
    end

A schedule from a list of tasks. Declare gantt, set dateFormat to describe how you are writing dates, and optionally axisFormat to control how they are printed on the axis. section groups related tasks.

Each task line is a name, a colon, then comma-separated attributes: an optional status (done, active, crit, milestone), an optional id, a start, and a duration. The start can be a date or after <id>, which is what makes the chart maintainable — shift one task and everything downstream follows. A duration of 0d with the milestone tag draws a diamond instead of a bar.

```mermaid
gantt
    title Release 4.0
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    section Build
    Implementation :done, impl, 2026-09-01, 10d
    Code freeze    :milestone, frz, 2026-09-11, 0d
    section Ship
    QA             :active, qa, after frz, 5d
    Release        :rel, after qa, 2d
```

gantt
    title Release 4.0
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    section Build
    Implementation :done, impl, 2026-09-01, 10d
    Code freeze    :milestone, frz, 2026-09-11, 0d
    section Ship
    QA             :active, qa, after frz, 5d
    Release        :rel, after qa, 2d

A pie chart is the shortest diagram Mermaid has: the word pie, an optional title, then a quoted label and a number per line. The percentages are calculated for you, so the numbers can be raw counts. Add showData after pie to print the values as well as the shares.

Worth knowing about the rest of the catalogue even if you never use most of it: stateDiagram-v2 for state machines, erDiagram for database relationships, classDiagram for object models, journey for user-journey scoring, mindmap for a tree of ideas, timeline for dated events, and quadrantChart for two-axis positioning. Each has its own grammar; the flowchart syntax will not carry across.

```mermaid
pie title Traffic by source
    "Organic search" : 52
    "Direct" : 27
    "Referral" : 14
    "Social" : 7
```

pie title Traffic by source
    "Organic search" : 52
    "Direct" : 27
    "Referral" : 14
    "Social" : 7

It draws in GitHub — in READMEs, issues, pull requests and wikis — and in GitLab, Notion, Obsidian, Azure DevOps, Joplin, many static site generators, and in this viewer, both on this page and in the live preview.

It does not draw in a plain text editor, in Slack or Discord, in most email clients, or in a strict CommonMark parser — all of those show the code. The important case for this site: exports do not draw diagrams. A Mermaid block in a Word or PDF export comes out as a code block containing the diagram source, because the exporter writes document structure rather than screenshots of a rendered page. If you need the picture in a document, render the diagram, screenshot it, and insert the image.

Unquoted labels with special characters. Brackets, colons, quotes and commas inside a label break the parser. Wrap the label in double quotes: A["Fetch (v2)"]. This is the single most frequent failure.

Wrong arrow for the diagram type. --> is a flowchart arrow; in a sequence diagram it is ->>. Mixing them produces a parse error with no useful message.

A node id that is a reserved word. end is the notorious one — it closes a block, so a node called end derails a flowchart. Rename it, or capitalise it.

A missing end. Every subgraph, loop, alt and opt needs one.

An indentation-sensitive type treated as free-form. mindmap and timeline read indentation as structure; flowcharts ignore it.

When a diagram fails here, the block falls back to showing its own source with a small error note, so the rest of the document keeps rendering. Fix the first error and re-render — Mermaid reports only one at a time.

```mermaid
flowchart LR
    A["Fetch (v2)"] --> B["Parse: JSON"]
    B --> C["Done"]
```

flowchart LR
    A["Fetch (v2)"] --> B["Parse: JSON"]
    B --> C["Done"]