Markdown Preview Mermaid Support 插件介绍

插件简介

Markdown Preview Mermaid Support 是一款为 VS Code 提供 Mermaid 流程图/时序图/甘特图等图形渲染的插件。它的核心作用是：
在 VS Code 内置的 Markdown 预览中（右侧预览窗格），直接渲染你写在 Markdown 里的 Mermaid 图，而不需要再切浏览器或其它工具。

简单说：写 Markdown + Mermaid，在 VS Code 里就能“所见即所得”预览图表。

---

适用场景

• 技术文档：系统架构图、流程图、时序图、模块交互图
• 设计评审/方案说明：用文本版本管理图表，不需要手画工具
• 学习笔记：记录算法流程、网络协议时序、业务流程
• 项目文档版本控制：图是“代码”，和 Markdown 一起进 Git，方便 diff/回滚

---

安装方式

1. 打开 VS Code
2. 左侧点击 扩展（Extensions） 图标
3. 搜索：Markdown Preview Mermaid Support
4. 选择插件后点击 Install（安装）
5. 安装完成后，重启或刷新一下 VS Code 即可生效

提示：通常插件名称里会写明 “Mermaid” 和 “Markdown Preview”，避免装错。

---

基本用法

1. 在 Markdown 中书写 Mermaid 代码块

在 .md 文件里，使用三引号代码块并标记 mermaid：

保存后，打开 Markdown 预览：

• 方式一：右键 → “Open Preview” / “打开预览”
• 方式二：快捷键（Windows / Linux）：Ctrl + K V
• 方式三：编辑区右上角的小预览按钮

你会在预览面板中看到上面的流程图被渲染出来。

2. 常见图表示例

流程图（Flowchart）

时序图（Sequence Diagram）

甘特图（Gantt）

---

与 VS Code 原生 Markdown 预览集成方式

安装后，这个插件会增强 VS Code 自带的 Markdown 预览，并不是单独开一个新的预览窗口。

• 你仍然使用 VS Code 的原生预览（Ctrl + Shift + V 或 Ctrl + K V）
• 插件自动识别 ```mermaid 代码块
• 在预览中把这些代码块替换成渲染好的图形

这样有几个好处：

• 体验统一：预览界面依然是原生 Markdown 预览
• 无需额外操作：只要写代码块即可
• 和其它 Markdown 扩展兼容：例如数学公式、高亮、目录等扩展

---

常见配置与小技巧

（不同版本细节略有不同，大体思路类似）

• 主题适配
  如果你使用深色主题，Mermaid 也可以设置为深色风格，通常可以在 VS Code 设置里搜索：

  • 关键词：mermaid / markdown mermaid
  • 找到类似 theme 或 darkMode 的配置（取决于当前插件版本）
  • 选择 dark 或自动跟随 VS Code 主题

• 图形尺寸与布局
  Mermaid 本身支持通过配置来控制布局，比如：
  

  通过 classDef / class 等方式，控制颜色、边框等。

• 避免图过大

  • 把复杂流程拆分成多个小图
  • 使用子图 subgraph，分块展示
  • 在 Markdown 里用多个 mermaid 代码块分章节展示

---

与其他方案对比

• 对比：手绘软件（Visio、ProcessOn、draw.io 等）

  • 手绘：上手快，但版本管理差，修改容易“推倒重来”
  • Mermaid：图是纯文本，可以 diff / merge / review，和代码一样管理

• 对比：在线 Mermaid 编辑器

  • 在线：需要切浏览器复制粘贴，不适合频繁小修改
  • VS Code 插件：写文档时就能直接看到图，改文档同时改图，效率更高

---

常见问题排查

• 预览中 Mermaid 不渲染，只显示代码？

  • 检查是否正确安装了 Markdown Preview Mermaid Support
  • 确认代码块语言是 ```mermaid（没有拼错、大小写正确）
  • 关闭预览重新打开一次，或重启 VS Code

• 报错：Syntax error in graph

  • 通常是 Mermaid 语法问题：
    • 箭头方向写错，如 ->>/--> 混用
    • 没对齐的 subgraph / end
    • 忘记给图标 ID 命名

• 深色主题下图看不清？

  • 打开 VS Code 设置，搜索 mermaid，检查是否有主题/颜色相关配置
  • 或者直接在 Mermaid 代码中自定义颜色（如前文 classDef 示例）

---

写作与团队协作建议

• 图和文字紧密配合
  在文档里：先简要解释业务/逻辑，再紧跟一个 Mermaid 图表，让读者先“看图再看字”。

• 图的命名与分章节

  • 每个图的上方加标题（### 登录流程图、### 服务调用时序图）
  • 超过 1 屏的复杂图，建议拆为多个小图，便于阅读和维护

• 配合 Git 做文档评审

  • PR 中可以直接看到 Mermaid 代码的 diff
  • 评审人不需要本地打开绘图软件，只要在 VS Code 里打开 Markdown 预览即可看到效果

---

小结

• Markdown Preview Mermaid Support 的核心价值：
  • 在 VS Code 原生 Markdown 预览中直接渲染 Mermaid 图
  • 用“写代码”的方式画流程图/时序图/甘特图
  • 适合团队文档、技术方案、学习笔记、版本化管理图表

如果你日常已经在用 VS Code 写 Markdown，又经常需要画流程图/架构图，非常推荐安装这款插件，把“画图”这件事变成“写文本 + 预览渲染”的自然一环。