Embedding Mermaid diagrams in Markdown: copy, paste, render anywhere

The power of Mermaid is that it's pure text. A diagram is just a string — you can paste it into a GitHub README, a Notion database, a GitLab wiki, or your Sphinx docs site, and it renders without extra setup. But each platform has its quirks. This guide shows you exactly how to embed Mermaid in every major platform and avoid common pitfalls.

Mermaid in GitHub (README, issues, PRs)

GitHub natively renders Mermaid in Markdown. Just wrap your diagram in a triple-backtick fence with the mermaid language specifier:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Continue]
    B -->|No| D[Stop]
```

Supported in:

• README files (*.md)
• Issues and issue comments
• Pull request descriptions and review comments
• GitHub Discussions
• GitHub Pages (Jekyll, Hugo, etc. via mermaid.min.js)

Quirks:

• Very large diagrams (300+ nodes) may fail silently. Keep diagrams under 150 nodes for reliability.
• Dark mode support is automatic; no manual styling needed.
• GitHub doesn't support all Mermaid directives (e.g., %%{init: {...}}%% for custom configs has limited support in some versions). Test on your version first.

Example in a PR description:

## What this PR does
Adds a new payment flow:

```mermaid
graph LR
    A[User] -->|Clicks Pay| B[Stripe Form]
    B -->|Token| C[Backend API]
    C -->|Webhook| D[Update DB]
    D -->|Success| A
```

This replaces the old hardcoded payment handler.

Mermaid in GitLab (Wiki, issues, Markdown files)

GitLab also natively supports Mermaid with the same fence syntax:

```mermaid
flowchart TD
    A[Build] --> B[Test]
    B --> C{Pass?}
    C -->|Yes| D[Deploy]
    C -->|No| E[Notify]
```

Supported in:

• Repository Markdown files (.md)
• Wiki pages
• Issues and merge requests
• Snippets

Quirks:

• The init directive works more reliably than on GitHub, so you can include config:

```mermaid
%%{init: {'theme': 'dark', 'flowchart': {'maxWidth': 500}}}%%
flowchart TD
    ...
```

Mermaid in Notion (unofficial, via embeds)

Notion doesn't natively parse Mermaid code blocks, but you can use embed blocks to render Mermaid from external sources:

1. Create a simple HTML page or use a CDN service that serves Mermaid diagrams.
2. Embed the page in Notion using the /embed command.

Workaround 1: Use a Mermaid-to-image converter

• Export your diagram to PNG/SVG from MermaidCreator, then upload the image to Notion.
• Pros: Always works, looks crisp.
• Cons: Not editable in Notion, requires re-export on changes.

Workaround 2: Link to an external diagram viewer

• Save your Mermaid code to a GitHub Gist or a Mermaid live editor link.
• Paste the link in Notion; visitors can click through to edit or view.

Workaround 3: Use a Notion integration

• Some Notion plugins (like Mermaid for Notion) embed Mermaid as SVG. Install from the Notion plugin marketplace.
• Cons: Requires a third-party app; may have API limits.

Mermaid in Sphinx and MkDocs (Python docs)

Both Sphinx (Python docs) and MkDocs (static site generator) support Mermaid via plugins.

Sphinx (with sphinxcontrib-mermaid)

Install:

pip install sphinxcontrib-mermaid

Add to conf.py:

extensions = ["sphinxcontrib.mermaid"]

Then use in .rst files:

.. mermaid::

    graph TD
        A[API Endpoint] --> B[Handler]
        B --> C[Response]

MkDocs (with pymdown-extensions)

Add to mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Then use in Markdown:

```mermaid
graph LR
    A[Input] --> B[Process] --> C[Output]
```

Mermaid in Jekyll and Hugo (static site generators)

Jekyll (with mermaid gem or CDN)

Add to your Gemfile:

gem "jekyll-mermaid"

Or load from CDN in your layout:

<script async src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

Then use Mermaid code blocks in Markdown as usual.

Hugo

Add the Mermaid script to your site's base template (layouts/baseof.html):

{{ with resources.Get "js/mermaid.min.js" }}
  <script async src="{{ .RelPermalink }}"></script>
{{ end }}

Then use Mermaid fenced code blocks in Markdown content.

Mermaid in Jira and Confluence (Atlassian)

Confluence

Use the official Mermaid for Confluence plugin (available in the Atlassian Marketplace).

Once installed, create a macro in Confluence:

{mermaid}
graph TD
    A[Task] --> B[Subtask]
    B --> C[Done]
{mermaid}

Jira

Jira doesn't have native Mermaid support, but you can:

1. Embed images exported from MermaidCreator.
2. Link to external Mermaid diagrams in attached documentation.
3. Use a custom Jira add-on for Mermaid rendering.

Platform comparison table

Platform	Native Support	Syntax	Dark Mode	Config Directives	Notes
GitHub	✅ Yes	```mermaid	Auto	Limited	Works in README, issues, PRs
GitLab	✅ Yes	```mermaid	Auto	✅ Full	Works in wiki, issues, MRs
Notion	❌ No	N/A	N/A	N/A	Use embeds or image exports
Sphinx	✅ Plugin	.. mermaid::	✅ Yes	✅ Yes	Requires sphinxcontrib-mermaid
MkDocs	✅ Plugin	```mermaid	✅ Yes	✅ Yes	Requires pymdown-extensions
Confluence	✅ Plugin	{mermaid}...{mermaid}	✅ Yes	✅ Yes	Requires Atlassian add-on
Jira	❌ No	N/A	N/A	N/A	Use image exports or links

Best practices for portable diagrams

1. Use standard Mermaid syntax — avoid features that are new or niche. Test on your target platform.
2. Keep diagrams readable at small sizes — many platforms render in sidebars or narrow columns.
3. Use color sparingly — rely on shape and layout for clarity; color is a bonus.
4. Test on light and dark themes — ensure labels are readable on both.
5. Include a text fallback — if Mermaid rendering fails, provide a link to the diagram in the editor.

Example fallback in Markdown:

```mermaid
graph LR
    A[Request] --> B[Response]
```

> Can't see the diagram? View it [here](/playground) or [as an image](/diagrams/request-response.png).

Example: embedding Mermaid in a multi-platform workflow

You write a diagram once in the MermaidCreator editor:

graph TD
    A["Diagram in MermaidCreator"]
    B["Export Mermaid code"]
    C["Paste in GitHub README"]
    D["Paste in Sphinx docs"]
    E["Paste in Notion (as link or image)"]
    
    A --> B
    B --> C
    B --> D
    B --> E

That one diagram appears in your README, your docs site, and your project wiki — all from the same source. When you update the diagram, you update every instance.

FAQ

Can I embed Mermaid directly in HTML without a CDN? Yes. Download mermaid.min.js and host it locally, or use npm install mermaid in a Node.js project.

Which Mermaid features work on all platforms? Flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, and Gantt charts. Newer formats (sankey, pie charts, mindmaps) may not render on older platform versions.

How do I style Mermaid diagrams across platforms? Use the init config directive to set themes and colors. Most platforms support it, but GitHub has limited support — check their docs first.

Create your diagrams once in MermaidCreator at /playground, export the code, and paste it everywhere your team collaborates.