How GitHub renders Mermaid
GitHub renders Mermaid diagrams from fenced code blocks with the mermaid language tag. They work in READMEs and other markdown files, issues, pull requests, discussions, and wikis.
Rendering happens in GitHub's own sandboxed pipeline, with a Mermaid version that GitHub controls and upgrades on its own schedule. That version usually lags behind the newest Mermaid release, which is the root cause of most "works locally, breaks on GitHub" surprises.
```mermaid
flowchart LR
dev[Write Mermaid] --> check[Check compatibility]
check --> ship[Ship to README]
```What works reliably
The long-stable diagram types are the safest bets: flowchart / graph, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, and journey.
Plain node shapes, labeled edges, subgraphs, and standard directions (TD, LR) render consistently. If your diagram only uses these, it will almost always survive the trip.
What commonly breaks
Newer diagram types (timeline, mindmap, quadrantChart, sankey, block, architecture and other beta types) only work once GitHub's deployed Mermaid version includes them. Verify on GitHub itself before committing to one in a README.
Interactive features are disabled: click directives and links inside diagrams do not work in GitHub's sandbox.
Theme and init directives (%%{init: ...}%%) may be ignored or interact badly with GitHub's own light and dark themes. Diagrams that depend on custom colors for meaning can become unreadable.
Very large diagrams can fail to render or get cut off. GitHub also renders diagrams inside a fixed-width column, so extremely wide flowcharts become hard to read even when they technically render.
A lowercase 'end' inside flowchart node labels is a classic parse trap — capitalize it.
Debugging a diagram that GitHub rejects
GitHub shows a generic error box rather than a detailed parse message. To find the actual failing line, paste the same source into a Mermaid editor with real diagnostics.
The MermaidPen studio renders with Mermaid 11, points at the failing line, flags GitHub-risky syntax with the GitHub-safe preset, and can strip brittle directives automatically.
Pre-publish checklist
Stick to the stable diagram types unless you have verified the newer type renders in your repository.
Remove %%{init}%% theme blocks, or accept that GitHub may override them.
Avoid click directives; treat diagrams as static images.
Keep diagrams narrow and split dense ones into several smaller diagrams.
For guaranteed rendering (release pages, marketing README sections), export an SVG and embed the image instead — keep the Mermaid source next to it as the source of truth.