在 Markdown 中嵌入 Mermaid 图表的完整方案

Mermaid 的"图表即代码"理念让技术文档编写者能够以纯文本方式维护图表，但在实际工作中，如何将 Mermaid 语法正确地嵌入到各种 Markdown 平台和文档工具中，仍然是一个常见痛点。不同平台对 Mermaid 的支持程度差异很大，有些原生渲染，有些需要插件，还有些完全不支持。

本文将系统梳理主流 Markdown 平台和文档工具对 Mermaid 的支持情况，并为每种场景提供详细的嵌入方案和配置步骤，帮助你无论在什么平台都能优雅地展示 Mermaid 图表。

原生支持 Mermaid 的平台

以下平台无需额外配置，直接按照标准语法书写即可自动渲染 Mermaid 图表。

GitHub

GitHub 在 2022 年正式原生支持 Mermaid 图表，覆盖 Issues、Pull Requests、Discussions、Wiki 以及仓库中的 Markdown 文件。

使用方法：在 Markdown 文件中使用标准的代码块语法，标注语言为 mermaid：

```mermaid
graph LR
    A[需求分析] --> B[技术设计]
    B --> C[代码开发]
    C --> D[测试验收]

**渲染效果**：

```mermaid
graph LR
    A[需求分析] --> B[技术设计]
    B --> C[代码开发]
    C --> D[测试验收]

注意事项：

• 代码块内必须包含有效的 Mermaid 语法，否则不会渲染
• 复杂图表在 GitHub 中的渲染尺寸可能受限，建议控制图表宽度
• GitHub 企业版（GitHub Enterprise Server）需要 3.4.0 以上版本才支持

GitLab

GitLab 同样原生支持 Mermaid，支持范围包括 Issue、Merge Request、Wiki、README 以及评论。

使用方法：与 GitHub 完全一致，使用 ```mermaid 代码块即可。

特殊功能：GitLab 还支持 ```mermaid 代码块中嵌入 click 交互事件，点击节点可以跳转到指定 URL，这在文档中构建导航非常有用。

Notion

Notion 在 2023 年添加了对 Mermaid 的原生支持，可以在任意页面中直接创建和编辑 Mermaid 图表。

使用方法：

1. 在 Notion 页面中输入 /mermaid 或 /code 后选择 Mermaid
2. 在弹出的代码编辑器中输入 Mermaid 语法
3. 点击外部区域即可实时渲染

特点：

• 支持实时预览，修改代码后图表自动更新
• 可以拖动调整图表显示大小
• 支持导出为图片（PNG 格式）
• 在数据库视图和模板中也能使用

需要插件或配置支持的平台

VS Code

VS Code 本身不直接渲染 Mermaid，但通过扩展可以实现完美的编辑和预览体验。

推荐扩展：

配置步骤：

1. 打开 VS Code 扩展市场（Ctrl+Shift+X）
2. 搜索 "Markdown Preview Mermaid Support"
3. 点击安装
4. 打开包含 Mermaid 代码块的 Markdown 文件
5. 按 Ctrl+Shift+V 打开预览，即可看到渲染后的图表

进阶技巧：在 settings.json 中配置 Mermaid 主题：

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

MkDocs

MkDocs 是 Python 生态中最流行的静态文档站点生成器，配合插件可以实现 Mermaid 渲染。

推荐方案：使用 mkdocs-mermaid2-plugin

安装与配置：

pip install mkdocs-mermaid2-plugin

在 mkdocs.yml 中添加：

plugins:
  - mermaid2

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

使用方法：在 Markdown 中直接使用标准 Mermaid 代码块，构建时会自动转换为 SVG 嵌入页面。

Docusaurus

Docusaurus 是 Meta 开源的文档站点框架，v2 及以上版本通过插件支持 Mermaid。

安装插件：

npm install @docusaurus/theme-mermaid

配置 docusaurus.config.js：

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

完成配置后，所有 ```mermaid 代码块会自动渲染为图表，无需额外操作。

VuePress / VitePress

VuePress 2 和 VitePress 均支持通过 Markdown 插件集成 Mermaid。

VitePress 配置示例：

npm install markdown-it-mermaid

在 .vitepress/config.ts 中：

import mdMermaid from 'markdown-it-mermaid';

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

博客平台方案

Hexo

Hexo 用户可以通过渲染器插件支持 Mermaid。

推荐插件：hexo-filter-mermaid-diagrams

npm install hexo-filter-mermaid-diagrams

在 _config.yml 中启用：

mermaid:
  enable: true
  theme: default

Hugo

Hugo 从 v0.93.0 开始内置 Mermaid 支持，通过短代码或自定义模板实现。

使用方法：在模板文件中引入 Mermaid JS，然后在内容中使用 ```mermaid 代码块。

在 layouts/_default/baseof.html 的 </body> 前添加：

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

在文章 Frontmatter 中启用：

---
mermaid: true
---

Jekyll

Jekyll 可以通过 jekyll-mermaid 插件或直接在模板中引入 Mermaid JS。

简单方案（无需插件）：在 _layouts/post.html 中引入 Mermaid，所有文章即可支持。

通用替代方案：导出为图片

当目标平台完全不支持 Mermaid（如微信公众号、知乎、CSDN 等传统富文本编辑器）时，将图表导出为图片是最可靠的方案。

使用 Mermaid2Img 导出

Mermaid2Img 专为这种场景设计：

1. 打开 Mermaid2Img 网站
2. 粘贴 Mermaid 代码，实时预览效果
3. 选择导出格式（推荐 PNG 用于网页，SVG 用于印刷）
4. 下载高清图片，直接插入到不支持 Mermaid 的编辑器中

各场景推荐格式：

使用 Mermaid CLI 批量导出

对于需要批量处理多个图表的场景，可以使用 Mermaid CLI：

# 导出单个文件
mmdc -i diagram.mmd -o output.png

# 批量导出目录下所有文件
for f in *.mmd; do mmdc -i "$f" -o "${f%.mmd}.png"; done

各平台支持情况总览

最佳实践与常见问题

1. 优先选择原生支持平台

如果团队正在选型文档平台，建议优先考虑 GitHub/GitLab Wiki、Notion、Docusaurus 等原生支持 Mermaid 的工具，可以省去大量配置和维护成本。

2. 图表宽度控制

在网页中展示时，过宽的图表可能导致横向滚动条。可以通过 Mermaid 的 subgraph 分组或调整布局方向（使用 TD 代替 LR）来优化显示效果。

3. 语法兼容性

不同平台使用的 Mermaid 版本可能不同，较新的语法特性（如某些图表类型或样式选项）可能在旧版本中无法渲染。建议在本地先用最新版本验证，再提交到目标平台。

4. 版本控制策略

由于 Mermaid 图表是纯文本，强烈建议将 .mmd 文件或包含 Mermaid 代码的 Markdown 文件纳入 Git 版本控制。每次修改都有完整的历史记录，便于团队协作和回滚。

5. 混合使用方案

在实际项目中，可以组合使用多种方案：

• 技术文档仓库（GitHub/Docusaurus）直接使用原生 Mermaid
• 对外分享的博客文章导出为高清图片
• 内部 Wiki（Notion）使用实时编辑功能

结语

Mermaid 的跨平台兼容性是它作为"图表即代码"工具的核心优势之一。从代码仓库到文档站点，从个人笔记到团队协作，几乎所有主流平台都能找到合适的嵌入方案。对于不支持 Mermaid 的平台，借助 Mermaid2Img 等导出工具也能轻松获得高质量的图表图片。

选择合适的嵌入方案，让 Mermaid 成为你技术文档和团队协作的得力助手。