Mermaid diagrams for docs, PRs, and READMEs (2026 guide)

Why Mermaid won

Diagrams in docs have historically been either (a) painful to author (Visio, draw.io, Lucid) or (b) rendered as static images that don't stay in sync with the code they describe. Mermaid solved both - you write the diagram as text, commit it alongside the code, and every modern doc platform renders it inline:

• GitHub - Mermaid in .md files since 2022.
• GitLab - since 2020.
• Notion - via /mermaid block since 2023.
• Obsidian - via built-in support.
• Docusaurus, Astro, MkDocs, Zola - all render Mermaid in Markdown.
• VS Code - Markdown Preview Mermaid Support extension.

If your team writes docs in any of those, Mermaid is the format.

The nine diagram types worth knowing

Mermaid 11 supports 15+ diagram types. The ones you'll actually use:

Flowchart - decision trees, workflows, request paths. Most common.

flowchart TD
  A[User visits] --> B{Signed in?}
  B -- Yes --> C[Show dashboard]
  B -- No --> D[Landing page]

Sequence diagram - API interactions, message passing, protocols.

sequenceDiagram
  User->>Web: POST /login
  Web->>Auth: verify credentials
  Auth-->>Web: JWT
  Web-->>User: 200 { token }

State diagram - UI states, order status, connection lifecycle.

Class diagram - object relationships, database ER (though ER diagrams are their own type in Mermaid).

ER diagram - database schema relationships. Cleaner than the class diagram for DB modeling.

Gantt - project timelines. Verbose to write; great for visual comms.

Pie - quick percentage breakdowns. Rarely the right chart, but sometimes.

Mindmap - hierarchical concept maps. Good for early planning.

Timeline - historical or roadmap timelines.

Mermaid Editor has templates for all of these - pick a diagram type, edit the template, see the live render.

The GitHub / GitLab embed

Both platforms render Mermaid inside triple-backtick blocks tagged mermaid:

```mermaid
flowchart LR
  A --> B --> C
```

That renders as a diagram in the file preview, PRs, issues, wiki pages. Works on both GitHub.com and GitHub Enterprise.

Same syntax on GitLab. Same on Notion. Same on Docusaurus + @docusaurus/theme-mermaid plugin.

The syntax gotchas

1. Direction matters. flowchart TD (top-down) vs LR (left-right) drastically changes readability. Wide diagrams work in LR; tall ones work in TD.

2. Node labels with special characters. Parentheses and brackets in labels break parsing unless quoted:

A["I'm a (special) label"]

3. Escape newlines. Use <br> for line breaks inside a node label, not literal newlines.

4. Node ID vs label. A[User dashboard] - A is the ID, User dashboard is the display label. Reference the ID, not the label, in arrows.

5. Subgraphs are your friend. Group related nodes with subgraph name ... end. Auto-clusters visually.

Exporting to PNG or SVG

GitHub / GitLab render Mermaid inline in the browser - no export needed. But for slides, external docs, or presentations:

• SVG - scales infinitely, tiny file size, works in every design tool (Figma, Sketch, Illustrator). Default for print or slides.
• PNG - needed for platforms that don't accept SVG (some email clients, older CMSes).

Mermaid Editor exports both. SVG for anything that scales; PNG for anything that doesn't.

After export, run SVG output through SVG Optimizer - Mermaid's rendered SVG has some redundant markup that can shrink 20-40%.

The four-node rule

Diagrams beyond 15-20 nodes stop being helpful - they look impressive but nobody reads them. Two mitigations:

• Split into multiple diagrams. One per concern (auth flow, checkout flow, error handling).
• Collapse detail into subgraphs. The reader can drill into the group only if they care.

Rule of thumb: if your diagram is wider than a laptop screen, it's too complex for the doc.

When Mermaid isn't the right choice

Three cases:

1. Free-form illustrations. Mermaid is grammar-driven - you get flowcharts and sequences, not arbitrary shapes. For UI mockups, use Figma. For architecture diagrams with cloud provider logos, use Excalidraw or draw.io.

2. Very complex hierarchies. Mermaid's auto-layout can produce cramped output for wide trees. For anything with 30+ nodes, a hand-laid diagram in Figma or Whimsical wins.

3. Anywhere Mermaid isn't rendered. Confluence Cloud has partial support (via a plugin). Legacy Confluence, most email clients, and Google Docs don't render Mermaid - for those, export to SVG/PNG once and embed the image.

The doc-writer's shortlist

Every serious repo should ship these three diagram categories, whether in README.md or a docs/ folder:

1. Architecture - a flowchart or a diagram showing the major components and how they connect. One diagram total.
2. Request lifecycle - a sequence diagram for the primary user flow (login, checkout, whatever the product's core loop is).
3. State - a state diagram for anything with meaningful states (job status, order status, chat session state).

Three diagrams. Fifteen minutes to write. Save hundreds of hours of "wait, how does this work again?" over the project's life.

Related tools

• Mermaid Editor - draft and export diagrams.
• Markdown to HTML - for previewing Markdown that includes Mermaid before pushing.
• ASCII Art Generator - for README banners next to the diagrams.
• SVG Optimizer - shrink exported SVGs before committing.