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:
- Opening fence: three backticks +
mermaidon the same line. - Diagram code on following lines.
- Closing fence: three backticks alone on a line.
- No indentation of the fence delimiters (some renderers are picky).
Preview in the editor or diagram tools hub before pushing.
Where Mermaid renders (2026)
| Platform | Native Mermaid | Notes |
|---|---|---|
| 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:
| Syntax | Shape |
|---|---|
[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:
- One diagram per section — do not stack five flowcharts vertically.
- Under ~25 nodes — large graphs slow page load and fail on mobile.
- Label edges —
A -->|HTTP| Bnot bare arrows. - Subgraphs for layers — Client / API / Data reads instantly.
- 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.
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:
| Limit | Guidance |
|---|---|
| ~60 KB diagram source | Split if approaching |
| ~50 nodes | Degrade render time |
| Nesting depth | Keep subgraphs shallow |
| Special characters | Quote labels with ["text with (parens)"] |
If rendering fails silently, simplify the diagram or check for syntax errors on mermaid.live.
Common syntax errors
| Error | Symptom | Fix |
|---|---|---|
| Wrong fence tag | Code block, not diagram | Use ```mermaid not ```md |
| Unquoted special chars | Parse error | Wrap label in quotes |
graph vs flowchart | Older syntax | Prefer flowchart in new docs |
| Semicolons in labels | Breaks parser | Use quotes or rephrase |
| HTML in labels | Stripped / error | Plain text only |
Run diagram inventory on repos with many Mermaid blocks.
When not to use Mermaid
| Scenario | Better alternative |
|---|---|
| Pixel-perfect UI mockup | Figma screenshot |
| Geographic map | Real map image |
| Complex ER with 40 tables | Dedicated DB doc tool |
| Email / PDF | Export PNG first |
| Slack announcement | PNG attachment |
Mermaid excels at logic and flow, not visual design.
Export Mermaid to PNG/SVG
For platforms without native Mermaid:
- Prototype in diagram tools.
- Export via mermaid.live → Actions → PNG/SVG.
- Commit image to
docs/images/with alt text. - Keep the Mermaid source in a comment or separate
.mdfor 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.
Related articles
- GitHub README guide — Mermaid in project front pages
- CommonMark vs GFM — Mermaid as GFM extension
- Docs-as-code guide — diagrams in CI
- VS Code Markdown guide — preview extensions
- Markdown code blocks — fenced block fundamentals
Quick reference
| Diagram keyword | Type |
|---|---|
flowchart TD / flowchart LR | Flowchart |
sequenceDiagram | Sequence diagram |
classDiagram | Class diagram |
stateDiagram-v2 | State diagram |
erDiagram | Entity-relationship |
gantt | Gantt chart |
pie | Pie chart |
gitGraph | Git 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.
A tutorial on adding diagrams and equations to Markdown using ready-made libraries — browse and copy Mermaid templates and KaTeX/LaTeX equations, then validate them before you commit.
The in-depth GitHub README playbook — star-winning structure, GFM tables and alerts, Mermaid diagrams, profile READMEs, badges, CI snippets, anti-patterns, and a copy-paste template.
A power-user tutorial for advanced Markdown tasks — diffing revisions, validating Mermaid, redacting secrets, normalizing structure, merging and splitting docs, and managing footnotes.