Mermaid in Markdown — the fence, where it renders, and how to upgrade it
A ```mermaid code fence turns Markdown into diagrams — on the platforms that support it. This guide covers where fences render natively, where they need a plugin, and the three ways to get presentation-ready output instead of the default style.
Where ```mermaid fences actually render
GitHub and GitLab render ```mermaid fences in READMEs, issues, and PRs. Obsidian renders them in Reading View. VS Code renders them in Markdown Preview with an extension.
Most static site generators (Hugo, Jekyll, MkDocs, Docusaurus) need a Mermaid plugin or a client-side script before fences render on the published site.
Plain-text viewers, most email clients, and tools that treat Markdown as text show the raw fence. For those destinations, embed the diagram as an image instead.
Step-by-step
A Mermaid diagram in Markdown is a fenced code block whose language is mermaid — three backticks, the word mermaid, your diagram source, three backticks.
On GitHub or GitLab the fence renders on its own, in the default style. In an SSG, wire up the Mermaid plugin. Anywhere else, plan for an image.
For docs and READMEs people actually read: the VS Code extension shows beautified fences while you write, the bd CLI batch-converts Markdown diagrams to polished SVGs in CI, and a saved embed URL drops a presentation-ready image into any Markdown with plain image syntax.
Frequently asked questions
How do I add a Mermaid diagram to a Markdown file?
Use a fenced code block with mermaid as the language: three backticks, mermaid, then your diagram source, then three closing backticks. Renderers that support Mermaid pick it up from the fence language.
Does GitHub render Mermaid in Markdown?
Yes — GitHub has rendered ```mermaid fences in READMEs, issues, and pull requests since 2022, in Mermaid's default style. If you want the diagram to look presentation-ready instead, embed a beautified SVG with regular image syntax; GitHub proxies and displays it like any image.
Why doesn't my Mermaid block render on my site?
Your Markdown pipeline probably treats the fence as a plain code block. Static site generators need a Mermaid plugin or client script. The zero-config alternative is exporting the diagram as SVG and embedding it as an image — it renders everywhere Markdown images do.
How do I make Mermaid diagrams in Markdown look better?
Native renderers all show Mermaid's default style. To upgrade: preview beautified fences in VS Code with the extension, batch-convert with the bd CLI in CI, or swap the fence for a saved embed URL that serves a themed, presentation-ready SVG.
Does Typora or another Markdown editor render Mermaid?
Many do — Typora renders fences live, and most modern Markdown editors have at least preview support. What varies is styling control, which is where exporting a themed SVG gives every destination the same polished output.
Can an AI agent maintain the diagrams in my Markdown docs?
Yes. Because the diagram is text inside the file, an agent can edit the fence like any code, and the bd CLI or editor plugins can render the result to SVG or PNG programmatically — no GUI in the loop.