How to embed Mermaid diagrams
Some tools draw Mermaid for you from plain text; others need an exported image. Here is where it renders natively, how to embed it on each platform, and the fallback when a tool cannot.
- 01
Build the diagram
Open the editor, write or paste your Mermaid, and confirm it renders the way you want.
- 02
Copy the source or export an image
For platforms that render Mermaid natively, copy the fenced ```mermaid Markdown block. For everywhere else, export an SVG or PNG.
- 03
Paste it where it belongs
Paste the Mermaid block into a native platform, or drop the exported image into a doc, slide or email. Keep the source in your repo so it stays editable.
Where Mermaid renders — platform by platform
| Platform | Mermaid support | How to embed |
|---|---|---|
| GitHub | Native | Paste a fenced ```mermaid block in any README, Markdown file, issue, pull request, discussion or wiki. GitHub draws it automatically. |
| GitLab | Native | Same fenced ```mermaid block works in Markdown, issues and merge requests on GitLab.com and self-managed instances. |
| Obsidian | Native | Write a ```mermaid code block in any note; Obsidian renders it in reading and live-preview modes — no plugin needed. |
| Notion | Native (code block) | Insert a /code block, set its language to “Mermaid”, paste the source, then use the block’s Preview / Split view to show the diagram. |
| Confluence | Needs an app | Confluence has no built-in Mermaid. Install a Marketplace app (e.g. a Mermaid macro) and paste the source into it, or embed an exported SVG/PNG. |
| Your own website | Native (add the script) | Drop the source in a <pre class="mermaid"> tag and load mermaid.js from a CDN — see the snippet below. Or embed an exported SVG for zero JavaScript. |
| Slack, Google Docs, email, PDF | Export an image | These do not render Mermaid. Export an SVG (crisp at any size) or PNG from the editor and paste that image. |
Platform features change — verify on your own account, especially for Notion previews and Confluence apps. “Native” means the diagram renders from source with no image upload.
Embed on your own website
Paste the Mermaid source into a <pre class="mermaid"> element and load the renderer from a CDN. This is the official ESM embed — copy it as-is:
<pre class="mermaid">
flowchart TD
A[Start] --> B{OK?}
B -->|Yes| C[Ship]
B -->|No| A
</pre>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>Pin a major version (here mermaid@11) so a future release cannot change your diagrams unexpectedly. For a static page with no JavaScript, export an SVG from the editor and reference it as an <img> instead.
GitHub README, step by step
GitHub is the most common target. For the full walkthrough — including why a block sometimes shows as code instead of a diagram — see how to embed a Mermaid diagram in a GitHub README.
Make a diagram first: open the Mermaid editor, or browse ready-made examples to copy.
Generating docs and diagrams on every release? Wire it into an automation — see AI workflow templates to auto-generate documentation diagrams with n8n.
Frequently asked questions
Which platforms render Mermaid without a plugin?
GitHub, GitLab and Obsidian render fenced ```mermaid blocks natively. Notion renders it inside a code block set to the Mermaid language with its preview view. Most other tools — Slack, Google Docs, email — need an exported SVG or PNG image instead.
How do I embed a Mermaid diagram in Notion?
Add a code block (type /code), change its language to “Mermaid”, and paste your diagram source. Notion shows a Preview / Split toggle on the block that renders the diagram. For a static copy, export an image from the editor and embed that instead.
How do I show a Mermaid diagram on my own website?
Put the source inside a <pre class="mermaid"> element and load mermaid.js from a CDN with mermaid.initialize({ startOnLoad: true }). The snippet on this page is a complete, working example. If you would rather ship no JavaScript, export an SVG and use it as an <img>.
Should I embed the source or an exported image?
Where the platform renders Mermaid (GitHub, GitLab, Obsidian, your own site), embed the source — it stays editable and diff-able in version control. Where it does not, export an SVG or PNG. SVG scales without blurring; PNG suits slides.
Does Confluence support Mermaid?
Not out of the box. You need a Marketplace app that adds a Mermaid macro, or you can paste an exported SVG/PNG image. Check your Confluence admin for the app you are allowed to install.