Mermaid in a GitHub README: The Rules Nobody Writes Down
Short answer: open a fenced code block with the literal lowercase word `mermaid`, put your diagram definition inside it, commit. GitHub renders it in the README, in issues, in pull requests, in discussions, and in wikis. No image to commit, no build step, no external service.
The syntax takes ten seconds. The failure modes are what cost people an afternoon.
How do I add a Mermaid diagram to a README?
A fenced block, tagged `mermaid`:
~~~ ```mermaid flowchart LR Dev[Push] --> CI[CI build] CI -->|pass| Stage[Staging] CI -->|fail| Dev Stage --> Prod[Production] ``` ~~~
That renders as a flowchart when the file is viewed on github.com. The file on disk is still plain Markdown, the diagram is still text, and a reviewer sees the change to the diagram as a normal diff rather than a swapped binary.
The same block works in issue bodies, pull request descriptions, discussion posts, wiki pages, and any `.md` file in the repository. It is the same renderer everywhere.
Why is my Mermaid diagram not rendering on GitHub?
Four causes account for nearly all of it.
The fence tag is wrong. It must be exactly `mermaid`, lowercase. `Mermaid` and `MERMAID` do not match, and GitHub falls back to showing the definition as a plain code block. A block that renders as monospace text rather than a diagram is almost always this.
There is a syntax error in the definition. GitHub shows an error box rather than failing silently, but the message is terse. Paste the definition into the Mermaid Live Editor, which points at the offending line, then paste it back.
GitHub's Mermaid version is behind the one you tested against. GitHub pins a specific Mermaid release. A diagram type or keyword added upstream last month may not render on github.com yet, even though it works perfectly in your local preview. If a brand-new feature is the only thing failing, this is why.
You are not looking at github.com. VS Code's built-in Markdown preview does not render Mermaid without an extension. Neither do most local Markdown viewers, npm README pages, or documentation sites that consume the file. The block renders on GitHub's website and in clients that implement it, and nowhere else by default.
That last one has a consequence worth taking seriously.
Where does a README Mermaid diagram actually render?
| Surface | Renders Mermaid | Notes | |---|---|---| | github.com README, issues, PRs, wikis | Yes | Native, no configuration | | VS Code Markdown preview | No, by default | Needs an extension | | npmjs.com package page | No | Shows the raw fenced block | | Most static site generators | Depends | Many need a plugin | | Slack, email, a slide | No | Needs an exported image or video |
The pattern is that the diagram is native where GitHub controls the renderer and absent everywhere else. For a README, that is usually fine, because the README's audience is on GitHub. It stops being fine the moment the same diagram is needed in a deck, a customer document, or a wiki that GitHub does not run.
At that point you need an export, and the format choice matters. SVG stays sharp and keeps its text; PNG is a fixed pixel grid that blurs when enlarged. Both routes, and the resolution trap, are covered in exporting Mermaid to PNG.
Should I commit a rendered image instead?
Almost never, for a GitHub-hosted README.
A committed image is a second copy of the diagram that looks authoritative and is not connected to the definition. Someone edits the flowchart, the PNG stays as it was, and every reader after that is reading documentation that is quietly wrong. There is no diff to catch it, because the image and the text are separate files and only one of them changed.
Native rendering removes the problem by removing the second copy. There is one artifact, it is the source, and a change to it is visible in review.
Commit an image only when the README has to render somewhere GitHub does not control — an npm package page being the common case — and when you do, generate it in CI from the definition rather than by hand, so it cannot drift.
What diagram types are worth putting in a README?
Not all of them. Three earn their place.
A flowchart for a build, release, or request path. It answers "what happens when I push" faster than three paragraphs.
A sequence diagram for anything involving more than two services talking to each other. A README that describes an authentication handshake in prose is a README nobody finishes. The syntax, and the mistakes that make one unreadable, are in our Mermaid sequence diagram guide.
An entity or class diagram for a data model, when the shape of the data is the thing a new contributor needs first.
What does not earn its place is a diagram of the directory tree, a diagram of concepts that are already a bullet list, and a diagram so large it has to be zoomed. A README diagram should fit on a laptop screen without scrolling. If it does not, split it, or write the paragraph instead.
What happens when the README diagram has to go in a presentation?
It changes jobs, and it usually fails at the new one.
In a README, the reader controls the pace. They scan, stop at the node they care about, trace one path, ignore the rest. The diagram can be dense because the reader is allowed to take their time with it.
On a slide, you control the pace. The audience sees the whole diagram at once, at a size set by the projector, while you are already talking. Density that was a feature in the repository becomes the reason nobody follows the explanation, which is the failure described in why static diagrams fail in presentations.
The definition is worth keeping either way. FluxDiagram takes the same Mermaid text you committed — flowchart, sequence, class, Gantt, or pie — and produces an animated version that reveals the diagram in order, exported as GIF, MP4, or WebM and embedded into PowerPoint, Google Slides, or Keynote. One source of truth, two rendering targets: GitHub renders the text for readers, and the animation carries it into the room.
Frequently asked questions
Does Mermaid work in GitHub issues and pull requests? Yes. The same fenced block renders in issue bodies, comments, pull request descriptions, discussions, and wiki pages. Sketching a proposed flow directly in a pull request description is one of the better uses of it.
Do I need to install anything for a README diagram? No. GitHub renders the block server-side. Install `@mermaid-js/mermaid-cli` only if you also want local previews or generated images.
Why does my diagram render on GitHub but not on npm? The npm package page does not implement Mermaid rendering, so it displays the fenced block as code. If the npm page matters, commit a generated SVG for that audience and keep the native block for GitHub.
FluxDiagram generates animated diagrams you embed into the deck you already have, in PowerPoint, Google Slides or Keynote. Paste the definition from your README into the Mermaid converter to see the animated version.