Mermaid diagrams

Mermaid turns text into diagrams. Use a ```mermaid fenced block and mdbin renders it live, right in your document — or open the diagram tool to draw one on its own and download it as a PNG.

Every example below shows its source first, then what it renders to.

Adding a diagram#

Open a fence with mermaid, write Mermaid code, and close it:

```mermaid
flowchart TD
  A[Start] --> B{Ready?}
  B -->|yes| C[Ship]
  B -->|no| A
```

Which renders as:

Click any diagram to open a larger, zoomable view.

Every diagram starts with a type keyword on the first line — flowchart, sequenceDiagram, classDiagram and so on. That keyword decides the syntax for everything after it, so the rest of this page is organised by type.

Flowcharts#

The workhorse. flowchart takes a direction: TD (top-down), LR (left-right), RL, or BT.

Node shapes#

The brackets around a label choose the shape:

```mermaid
flowchart LR
  A[Rectangle] --> B(Rounded)
  B --> C([Stadium])
  C --> D[[Subroutine]]
  D --> E[(Database)]
  E --> F((Circle))
  F --> G{Diamond}
  G --> H{{Hexagon}}
  H --> I[/Parallelogram/]
```

Links#

```mermaid
flowchart LR
  A -->|arrow| B
  B --- C
  C -.->|dotted| D
  D ==>|thick| E
  E ~~~ F
```

• --> arrow, --- open line
• -.-> dotted, ==> thick, ~~~ invisible (useful for nudging layout)
• Label a link with -->|text| or -- text -->
• Lengthen a link by adding dashes: ---> pushes the target a rank further away

Subgraphs#

Group related nodes. Links can cross in and out of a group freely:

```mermaid
flowchart TD
  Client --> API
  subgraph Backend
    API --> Worker
    Worker --> DB[(Postgres)]
  end
  DB --> Backup[(Backups)]
```

Styling a node#

```mermaid
flowchart LR
  A[Normal] --> B[Highlighted]
  style B fill:#b4232c,stroke:#7a1720,color:#ffffff
```

Use classDef plus class when several nodes share a look:

```mermaid
flowchart LR
  A --> B --> C
  classDef hot fill:#b4232c,color:#fff
  class B,C hot
```

Sequence diagrams#

For messages exchanged over time between participants.

```mermaid
sequenceDiagram
  autonumber
  participant U as User
  participant S as mdbin
  participant D as Database
  U->>S: Submit Markdown
  activate S
  S->>D: Insert document
  D-->>S: id + slug
  S-->>U: Share link
  deactivate S
  Note over U,S: The link is public but unguessable
```

• participant X as Label names a column; actor X draws a stick figure instead
• ->> solid arrow, -->> dashed reply, -x an ✗ end, -> plain line
• activate / deactivate draw the lifeline bar — or suffix the arrow with + and -
• Note left of X:, Note right of X:, Note over X,Y:
• autonumber numbers every message

Loops, conditionals and parallel blocks:

```mermaid
sequenceDiagram
  participant A as Agent
  participant S as Server
  loop Every 30s
    A->>S: Poll
  end
  alt Ready
    S-->>A: 200 OK
  else Still working
    S-->>A: 202 Accepted
  end
  par Notify
    S->>A: Webhook
  and Log
    S->>S: Write audit line
  end
```

Class diagrams#

```mermaid
classDiagram
  class Document {
    +string slug
    +string title
    -string ipHash
    +render() string
    +isExpired() bool
  }
  class Comment {
    +int anchor
    +displayName() string
  }
  Document "1" --> "many" Comment : has
  Document <|-- ForkedDocument
```

• Visibility: + public, - private, # protected, ~ package
• Relations: <|-- inheritance, *-- composition, o-- aggregation, --> association, ..> dependency, ..|> realisation
• Cardinality goes in quotes either side of the arrow
• <<interface>> above a member line marks a stereotype

State diagrams#

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: publish
  Published --> Expired: TTL elapses
  Published --> [*]: deleted
  Expired --> [*]: pruned
```

[*] is both the start and the end node. Nest with state Name { … }, and use <<choice>> or <<fork>> for branching. Note that a transition label cannot contain a colon — the parser reads the first colon as the start of the label.

Entity-relationship diagrams#

```mermaid
erDiagram
  USER ||--o{ DOCUMENT : publishes
  DOCUMENT ||--o{ COMMENT : receives
  DOCUMENT {
    bigint id PK
    string slug UK
    string title
    datetime expires_at
  }
```

Cardinality is written as a pair of symbols: || exactly one, o| zero or one, }o zero or many, }| one or many. The line is solid (--) for an identifying relationship and dotted (..) otherwise.

Gantt charts#

```mermaid
gantt
  title Release plan
  dateFormat YYYY-MM-DD
  axisFormat %d %b
  section Build
    Schema        :done,    des1, 2026-01-05, 5d
    API           :active,  des2, after des1, 6d
  section Ship
    Docs          :         des3, after des2, 3d
    Launch        :crit,    des4, after des3, 1d
```

Each task is Label :tags, id, start, duration. Tags include done, active, crit and milestone; after <id> chains a task to the end of another.

Pie charts#

```mermaid
pie showData
  title Where documents come from
  "Web editor" : 62
  "URL import" : 24
  "MCP agents" : 14
```

Mindmaps#

Indentation is the entire syntax — each level of indent is a level of the tree.

```mermaid
mindmap
  root((mdbin))
    Write
      Markdown
      Mermaid
    Share
      Short link
      Comments
```

Git graphs#

```mermaid
gitGraph
  commit id: "init"
  branch feature
  commit id: "editor"
  commit id: "export"
  checkout main
  merge feature
```

Other types#

Mermaid 11 also renders journey maps, quadrant charts, requirement diagrams, C4, timelines, sankey and XY charts. See the Mermaid documentation for the full syntax of every diagram type.

Theme aware#

Diagrams follow the page theme — toggle light/dark and they re-render to match. The diagram tool can export either theme as a PNG, or both at once as a zip, so a diagram you paste elsewhere matches wherever it lands.

Limits and safety#

• Diagrams render in Mermaid's strict security mode: no click handlers or scripts inside a diagram.
• Up to 25 diagrams per document, each up to 10,000 characters of source. These caps keep a single document from hanging the reader's browser.
• Diagrams render lazily as they scroll into view, so a long document stays responsive.

Tips#

• Keep node labels short — Mermaid lays diagrams out automatically, and shorter labels pack tighter.
• Pick the direction that fits: TD (top-down) for hierarchies and decisions, LR (left-right) for pipelines and wide fan-outs.
• Prefer many small diagrams over one giant one — they're easier to read and to zoom.
• If a label contains a bracket, colon, slash or quote, wrap it in double quotes: A["Controller: store()"]. This is the single most common cause of a diagram failing to render.
• A diagram that won't render usually has a typo in the first line — check the type keyword and its direction before anything else.