Using Mermaid in Markdown, GitHub, and Notion
Mermaid inside Markdown means diagrams that live in your docs and update with a text edit. Here is how to use it across the big platforms.
One of Mermaid's greatest strengths is that it drops straight into Markdown, the plain-text format that powers READMEs, wikis, docs sites, and note-taking tools everywhere. Embedding a Mermaid diagram in Markdown means your diagram is just part of the document - versioned with it, edited with it, and rendered inline wherever the Markdown is displayed. This guide covers exactly how to embed Mermaid across the platforms most people use: generic Markdown, GitHub, and Notion, along with the quirks each one has.
The core mechanism is the same everywhere: a fenced code block tagged with the `mermaid` language. Where the platforms differ is in whether they render it natively, what subset of Mermaid they support, and small syntax details. Getting these right means your diagrams render reliably and stay in sync with your docs. You can draft and validate your Mermaid first in the live editor at /diagram-tools/mermaid-editor, then paste the working code into your document with confidence.
Mermaid in generic Markdown
In Markdown, you embed a Mermaid diagram with a fenced code block whose language is `mermaid`. That is: open with three backticks immediately followed by the word `mermaid`, write your diagram definition on the lines below, and close with three backticks. Whether this actually renders depends on the Markdown processor - plain Markdown does not render diagrams on its own, but any processor with Mermaid support recognizes the `mermaid` language tag and renders the block as a diagram.
This is why the same Markdown file can show a rendered diagram on GitHub and a plain code block in a processor without Mermaid support. The text is identical and correct; rendering depends on the environment. Most modern documentation tools, static-site generators, and note apps either support Mermaid natively or via a plugin. When you write the Markdown, you are writing portable content - it renders wherever Mermaid is supported and degrades to readable text where it is not, which is a reasonable fallback.
Mermaid in GitHub and GitLab
GitHub renders Mermaid natively across the whole platform, which is a large part of why Mermaid became ubiquitous. You use the standard fenced code block tagged `mermaid` in any Markdown context - README files, issue descriptions, pull request comments, discussions, and wiki pages - and GitHub renders the diagram inline automatically. No configuration, no extension. This makes it trivial to include an architecture diagram in a README or a sequence diagram explaining a change in a pull request.
GitLab works identically with the same syntax and equally broad support. The practical tips for both: always include the `mermaid` language tag or you get a plain code block; keep diagrams reasonably sized since very large ones can render slowly or awkwardly in the constrained width of a file view; and validate complex Mermaid in a live editor first, because a syntax error typically shows as an error message or nothing rather than a partial diagram. Because the diagram is text in the repo, it versions and diffs like code, so a reviewer sees exactly what changed in a diagram within the pull request.
Mermaid in Notion
Notion supports Mermaid through its code block feature. You create a code block, set its language to Mermaid, and paste your diagram definition; Notion then offers to render it, showing the diagram alongside or in place of the code. This lets you keep diagrams inside Notion docs - architecture notes, project plans, design documents - as text you can edit rather than as pasted images that go stale. The workflow is a bit more manual than GitHub's automatic inline rendering but works well.
- Use a fenced code block tagged `mermaid` in Markdown; rendering depends on the processor supporting Mermaid.
- GitHub and GitLab render it natively everywhere - READMEs, issues, PRs, wikis - with no setup.
- In Notion, create a code block, set the language to Mermaid, and use its render option.
- Always include the `mermaid` language tag, or you get a plain code block.
- Validate complex diagrams in a live editor first, since errors often render as nothing.
- Keep diagrams reasonably sized for narrow file-view widths.
- Because the diagram is text, it versions and diffs with your docs and cannot silently drift.
Keeping diagrams in sync with docs
The whole payoff of Mermaid in Markdown is that diagrams stop drifting from documentation. When the diagram is text in the same file as the prose, updating it is part of the same edit that updates the words, and on platforms with version control the change is reviewable. This is the antidote to the classic problem of a docs page whose diagram is a screenshot from two years ago that no longer matches reality. Treat the diagram as part of the doc, and it stays as current as the doc.
To make this reliable, draft and validate your Mermaid before committing it, since a broken diagram in docs is worse than none. The live editor at /diagram-tools/mermaid-editor lets you confirm a diagram renders correctly before you paste it into your Markdown. And when you need a polished, precisely laid-out version for a presentation or an external document rather than an inline docs render, you can import the same Mermaid into Atlas Diagram Studio, refine it visually on the canvas at /diagrams, and export a clean image - keeping one text source for your docs and a polished export for slides.