Embed a Mermaid diagram in a GitHub README
GitHub renders Mermaid for you — drop the diagram in as a fenced code block and it draws itself. Here is the whole flow, plus the fallback for tools that do not support it.
- 01
Create your diagram
Open the Mermaid editor, write or paste your diagram, and check it renders the way you want.
- 02
Copy the Markdown block
Use the Markdown export button to copy a fenced ```mermaid code block to your clipboard.
- 03
Paste it into your README
Paste the block into README.md and commit. GitHub renders the fenced mermaid block as a diagram automatically — no image file needed.
What the block looks like
Anything between the ```mermaid fences becomes a diagram on GitHub:
```mermaid
flowchart TD
A[Start] --> B{OK?}
B -->|Yes| C[Ship]
B -->|No| A
```Need to make one first? Open the free Mermaid editor, build your diagram, then copy the Markdown block.
Generating docs and diagrams on every release? You can wire it into an automation — see AI workflow templates to auto-generate documentation diagrams with n8n.
Frequently asked questions
Does GitHub render Mermaid in README files?
Yes. GitHub natively renders fenced ```mermaid code blocks in README.md, issues, pull requests and discussions. You paste the text and GitHub draws the diagram — no image upload needed.
Why is my Mermaid block showing as code, not a diagram?
Check that the fence says exactly ```mermaid (lowercase) and that the syntax is valid. Render it in the editor here first to confirm it parses, then copy the Markdown block again.
Does this work on GitLab and other tools?
GitLab, Obsidian, Notion (via plugins) and many docs platforms also render Mermaid. For platforms that do not, export an SVG or PNG from the editor and embed that image instead.
Should I commit an image or the Mermaid source?
On GitHub, commit the Mermaid source in a fenced block — it stays editable and diff-able in pull requests. Use an exported SVG/PNG only where the platform cannot render Mermaid.