Complete Guide to Embedding Mermaid Diagrams in Markdown

Mermaid's "Diagram as Code" philosophy lets technical writers maintain diagrams as plain text, but in practice, correctly embedding Mermaid syntax into various Markdown platforms and documentation tools remains a common pain point. Different platforms vary widely in their level of Mermaid support—some render natively, some require plugins, and others don't support it at all.

This article systematically reviews Mermaid support across mainstream Markdown platforms and documentation tools, providing detailed embedding instructions and configuration steps for each scenario so you can elegantly display Mermaid diagrams no matter what platform you're on.

Platforms with Native Mermaid Support

The following platforms require no extra configuration—just write standard syntax and diagrams will render automatically.

GitHub

GitHub officially added native Mermaid support in 2022, covering Issues, Pull Requests, Discussions, Wiki, and Markdown files in repositories.

Usage: Use standard code block syntax in Markdown files, specifying the language as mermaid:

```mermaid
graph LR
    A[Requirements Analysis] --> B[Technical Design]
    B --> C[Code Development]
    C --> D[Testing & Acceptance]

**Rendered Result**:

```mermaid
graph LR
    A[Requirements Analysis] --> B[Technical Design]
    B --> C[Code Development]
    C --> D[Testing & Acceptance]

Notes:

• The code block must contain valid Mermaid syntax or it won't render
• Complex diagrams may have limited rendering dimensions on GitHub; control chart width
• GitHub Enterprise Server requires version 3.4.0 or higher for Mermaid support

GitLab

GitLab also supports Mermaid natively across Issues, Merge Requests, Wiki, README, and comments.

Usage: Identical to GitHub—use ```mermaid code blocks.

Special Feature: GitLab supports click interactive events within ```mermaid code blocks, allowing nodes to link to specific URLs—very useful for building navigation in documentation.

Notion

Notion added native Mermaid support in 2023, allowing you to create and edit Mermaid diagrams directly on any page.

Usage:

1. On a Notion page, type /mermaid or /code and select Mermaid
2. Enter your Mermaid syntax in the code editor that appears
3. Click outside the editor to render in real time

Features:

• Real-time preview—charts auto-update as you edit code
• Drag to resize chart display
• Supports export as images (PNG format)
• Works in database views and templates

Platforms Requiring Plugins or Configuration

VS Code

VS Code doesn't render Mermaid directly out of the box, but extensions provide a perfect editing and preview experience.

Recommended Extensions:

Setup Steps:

1. Open the VS Code Extensions marketplace (Ctrl+Shift+X)
2. Search for "Markdown Preview Mermaid Support"
3. Click Install
4. Open a Markdown file containing Mermaid code blocks
5. Press Ctrl+Shift+V to open the preview and see rendered charts

Pro Tip: Configure the Mermaid theme in settings.json:

{
  "markdown-preview-enhanced.mermaidTheme": "dark"
}

MkDocs

MkDocs is the most popular static documentation site generator in the Python ecosystem, and with plugins it can render Mermaid.

Recommended Solution: Use mkdocs-mermaid2-plugin

Installation and Configuration:

pip install mkdocs-mermaid2-plugin

Add to mkdocs.yml:

plugins:
  - mermaid2

extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js

Usage: Use standard Mermaid code blocks directly in Markdown; they will be automatically converted to SVG and embedded in the page during builds.

Docusaurus

Docusaurus is Meta's open-source documentation site framework. v2 and above support Mermaid via plugins.

Install Plugin:

npm install @docusaurus/theme-mermaid

Configure docusaurus.config.js:

module.exports = {
  themes: ['@docusaurus/theme-mermaid'],
  markdown: {
    mermaid: true,
  },
};

After configuration, all ```mermaid code blocks will automatically render as charts without any extra steps.

VuePress / VitePress

Both VuePress 2 and VitePress support Mermaid integration via Markdown plugins.

VitePress Configuration Example:

npm install markdown-it-mermaid

In .vitepress/config.ts:

import mdMermaid from 'markdown-it-mermaid';

export default {
  markdown: {
    config: (md) => {
      md.use(mdMermaid);
    }
  }
};

Blog Platform Solutions

Hexo

Hexo users can support Mermaid via renderer plugins.

Recommended Plugin: hexo-filter-mermaid-diagrams

npm install hexo-filter-mermaid-diagrams

Enable in _config.yml:

mermaid:
  enable: true
  theme: default

Hugo

Hugo has built-in Mermaid support since v0.93.0, implemented via shortcodes or custom templates.

Usage: Include the Mermaid JS in template files, then use ```mermaid code blocks in content.

Add before </body> in layouts/_default/baseof.html:

{{ if .Params.mermaid }}
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad: true});</script>
{{ end }}

Enable in article Frontmatter:

---
mermaid: true
---

Jekyll

Jekyll can support Mermaid via the jekyll-mermaid plugin or by directly including the Mermaid JS in templates.

Simple Solution (no plugin needed): Include Mermaid in _layouts/post.html, and all posts will support it.

Universal Alternative: Export as Images

When the target platform doesn't support Mermaid at all (e.g., WeChat Official Accounts, Zhihu, CSDN, and other traditional rich-text editors), exporting diagrams as images is the most reliable solution.

Using Mermaid2Img for Export

Mermaid2Img is specifically designed for this scenario:

1. Open the Mermaid2Img website
2. Paste your Mermaid code and preview the result in real time
3. Select an export format (PNG recommended for web, SVG for print)
4. Download the high-definition image and insert it directly into editors that don't support Mermaid

Recommended Formats by Scenario:

Batch Export with Mermaid CLI

For scenarios requiring batch processing of multiple diagrams, use the Mermaid CLI:

# Export a single file
mmdc -i diagram.mmd -o output.png

# Batch export all files in a directory
for f in *.mmd; do mmdc -i "$f" -o "${f%.mmd}.png"; done

Platform Support Overview

Best Practices and Common Issues

1. Prioritize Native-Support Platforms

If your team is selecting a documentation platform, we recommend prioritizing tools with native Mermaid support such as GitHub/GitLab Wiki, Notion, or Docusaurus. This saves significant configuration and maintenance costs.

2. Chart Width Control

When displaying on web pages, overly wide charts may cause horizontal scrollbars. Optimize display by using Mermaid's subgraph grouping or adjusting layout direction (use TD instead of LR).

3. Syntax Compatibility

Different platforms may use different Mermaid versions, so newer syntax features (such as certain diagram types or styling options) may not render on older versions. We recommend validating locally with the latest version first before submitting to the target platform.

4. Version Control Strategy

Because Mermaid diagrams are plain text, we strongly recommend including .mmd files or Markdown files containing Mermaid code in Git version control. Every modification has a complete history, facilitating team collaboration and rollbacks.

5. Hybrid Approach

In real-world projects, you can combine multiple solutions:

• Use native Mermaid directly in technical documentation repositories (GitHub/Docusaurus)
• Export high-definition images for externally shared blog articles
• Use the real-time editing feature for internal Wikis (Notion)

Conclusion

Mermaid's cross-platform compatibility is one of its core strengths as a "Diagram as Code" tool. From code repositories to documentation sites, from personal notes to team collaboration, almost all mainstream platforms offer a suitable embedding solution. For platforms that don't support Mermaid, export tools like Mermaid2Img make it easy to obtain high-quality chart images.

Choose the right embedding solution and let Mermaid become a powerful assistant for your technical documentation and team collaboration.