Mermaid: 6 diagram types side by side

Quick tour of the Mermaid types the renderer handles. Useful when designing a new doc and deciding which shape fits.

Flowchart — direction LR, the simplest case

flowchart LR
  A[Capture] --> B[Hub]
  B --> C[Any AI]
  B --> D[Per-project bundle]
  D --> C

When to use: showing how data or actions move through a small set of stages. The LR (left-to-right) direction reads naturally for a workflow.

Sequence diagram — actor-to-actor over time

sequenceDiagram
  Claude->>+mdfy: GET /hub/demo
  mdfy-->>-Claude: markdown + graph_data
  Claude->>+mdfy: GET /b/abc123?compact
  mdfy-->>-Claude: bundle digest

When to use: explaining a round-trip. The arrows distinguish call (filled) from return (dashed) and the +/- mark which actor is active.

Pie

pie title Time spent on mdfy (week of 2026-05-12)
  "Engineering" : 50
  "Demo seed expansion" : 18
  "Marketing + Launch prep" : 12
  "Conversations + meetings" : 10
  "Admin" : 10

When to use: proportions, when there are 3-6 categories. More than 6 and it gets unreadable.

Gantt

gantt
  title Launch runway
  dateFormat YYYY-MM-DD
  section Build
  Demo seed       :done,    a1, 2026-05-14, 1d
  Show HN draft   :active,  a2, 2026-05-15, 7d
  Pre-launch QA   :         a3, after a2, 5d
  section Launch
  Post Show HN    :crit,    b1, 2026-08-15, 1d
  Respond live    :crit,    b2, after b1, 1d

State diagram

stateDiagram-v2
  [*] --> Draft
  Draft --> Public: publish
  Draft --> Restricted: add allowed_emails
  Public --> Restricted: lock access
  Restricted --> Public: open access
  Public --> [*]: delete
  Restricted --> [*]: delete

ER

erDiagram
  USER ||--o{ DOCUMENT : owns
  USER ||--o{ BUNDLE : owns
  BUNDLE ||--o{ BUNDLE_DOCUMENT : contains
  DOCUMENT ||--o{ BUNDLE_DOCUMENT : included_in

When NOT to use Mermaid

If the diagram is showing more than 12 elements, or if the layout matters (e.g. a system architecture diagram where physical placement = something), Mermaid's auto-layout will fight you. Use a hand-drawn SVG instead.