Skip to content
All posts
6 min read
markdown
mermaid
diagrams
github
guide

Mermaid Diagrams in Markdown: Complete Guide for GitHub & Docs (2026)

Write Mermaid flowcharts, sequence diagrams, and Gantt charts in Markdown — GitHub README syntax, supported diagram types, styling, limits, and troubleshooting broken renders.

Diagrams in documentation used to mean maintaining a separate .png in assets/ and updating it every time the architecture changed. Mermaid lets you define flowcharts, sequence diagrams, and Gantt charts as text inside a Markdown fenced code block — version-controlled, diffable, and renderable on GitHub, GitLab, Obsidian, and most modern doc platforms.

GitHub added native Mermaid rendering in 2022. If your README still uses static architecture images from 2019, you are one fenced block away from diagrams that update with your code.

This guide covers every major diagram type, GitHub and GitLab syntax, styling, size limits, and how to prototype diagrams before committing them.

Basic syntax

Wrap Mermaid code in a fenced block with the mermaid language tag:

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do thing]
    B -->|No| D[Stop]
```

Rules:

  1. Opening fence: three backticks + mermaid on the same line.
  2. Diagram code on following lines.
  3. Closing fence: three backticks alone on a line.
  4. No indentation of the fence delimiters (some renderers are picky).

Preview in the editor or diagram tools hub before pushing.

Where Mermaid renders (2026)

PlatformNative MermaidNotes
GitHub README / issues / PRs✅Since Feb 2022
GitLab issues / MRs / wiki✅GLFM native
Obsidian✅Built-in
VS Code preview⚠️Extension required
Notion❌Screenshot or embed
Slack / Discord❌Export as image
Hugo / Docusaurus✅Plugin or built-in
npm package README✅GitHub renders on npmjs.com

For chat platforms, export PNG from the diagram tool and upload as an image.

Diagram types reference

Flowchart

Rendering diagram…

Direction: TD (top-down), LR (left-right), BT, RL.

Node shapes:

SyntaxShape
[text]Rectangle
(text)Rounded
([text])Stadium
[[text]]Subroutine
[(text)]Cylinder (database)
{text}Diamond (decision)

Sequence diagram

Rendering diagram…

Use for API flows, auth sequences, and incident timelines. Ideal for README "How it works" sections.

Class diagram

Rendering diagram…

Useful in library READMEs documenting object models.

State diagram

Rendering diagram…

Entity-relationship diagram

Rendering diagram…

Gantt chart

Rendering diagram…

Pie chart

Rendering diagram…

Git graph

Rendering diagram…

Styling and themes

Mermaid supports classDef and style directives:

Rendering diagram…

GitHub uses its own light/dark theme automatically — custom colors may look different in dark mode. Test both themes on GitHub by toggling appearance settings.

Keep styling minimal — over-styled diagrams are harder to maintain than unstyled ones.

Mermaid in GitHub READMEs

Best practices for README architecture diagrams:

  1. One diagram per section — do not stack five flowcharts vertically.
  2. Under ~25 nodes — large graphs slow page load and fail on mobile.
  3. Label edges — A -->|HTTP| B not bare arrows.
  4. Subgraphs for layers — Client / API / Data reads instantly.
  5. Alt text context — add a prose summary above the fence for screen readers.

Example for an API product README:

## Architecture

```mermaid
flowchart LR
    Client -->|Bearer token| API[Markdown API]
    API --> Render[render]
    API --> Redis[(Rate limit)]
    API --> DB[(Usage log)]
```

Pair with the GitHub README guide structure.

Mermaid in GitLab

GitLab GLFM renders Mermaid in issues, merge requests, wikis, and Markdown files. Syntax is identical to GitHub.

GitLab-specific: use #123 and @user cross-references in prose near diagrams — they do not work inside Mermaid node labels.

See GitLab Markdown guide.

Mermaid in Obsidian

Obsidian renders Mermaid natively in preview and publish. Use for vault dashboards:

```mermaid
flowchart TD
    Daily --> Projects
    Projects --> API
    Projects --> Blog
```

Large diagrams in Obsidian can lag — split into linked sub-diagrams. Obsidian guide.

Size limits and performance

GitHub imposes practical limits:

LimitGuidance
~60 KB diagram sourceSplit if approaching
~50 nodesDegrade render time
Nesting depthKeep subgraphs shallow
Special charactersQuote labels with ["text with (parens)"]

If rendering fails silently, simplify the diagram or check for syntax errors on mermaid.live.

Common syntax errors

ErrorSymptomFix
Wrong fence tagCode block, not diagramUse ```mermaid not ```md
Unquoted special charsParse errorWrap label in quotes
graph vs flowchartOlder syntaxPrefer flowchart in new docs
Semicolons in labelsBreaks parserUse quotes or rephrase
HTML in labelsStripped / errorPlain text only

Run diagram inventory on repos with many Mermaid blocks.

When not to use Mermaid

ScenarioBetter alternative
Pixel-perfect UI mockupFigma screenshot
Geographic mapReal map image
Complex ER with 40 tablesDedicated DB doc tool
Email / PDFExport PNG first
Slack announcementPNG attachment

Mermaid excels at logic and flow, not visual design.

Export Mermaid to PNG/SVG

For platforms without native Mermaid:

  1. Prototype in diagram tools.
  2. Export via mermaid.live → Actions → PNG/SVG.
  3. Commit image to docs/images/ with alt text.
  4. Keep the Mermaid source in a comment or separate .md for future edits.

API and automation

For docs pipelines that validate diagram presence:

curl -X POST https://trymarkdownviewer.com/api/v1/extract/code-blocks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "```mermaid\nflowchart TD\n  A-->B\n```"}'

Returns fenced blocks with language tags — filter language === "mermaid" in CI.

Quick reference

Diagram keywordType
flowchart TD / flowchart LRFlowchart
sequenceDiagramSequence diagram
classDiagramClass diagram
stateDiagram-v2State diagram
erDiagramEntity-relationship
ganttGantt chart
piePie chart
gitGraphGit branch graph

Mermaid turns diagrams into text you can review in PRs. Start with one sequence diagram in your README, keep it under twenty lines, and update it when the architecture changes — your docs will stay honest longer than any screenshot.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.