Mermaid:让技术文档中的流程图跟着文本更新

技术文档 · 流程图

测试流程刚加了一道人工复核，文档里的流程图却还是旧截图。修改说明文字只要几秒，重新打开绘图文件、加节点、导出图片，再替换文档中的图片，反而成了最容易被拖后的工作。

Mermaid 适合处理这种经常改动的图。节点、分支和连线写在文本里，修改图的定义后，支持它的编辑器会重新渲染图形；文档与图可以一起提交和审阅。

从一段文本开始

Mermaid 是开源的图表工具，使用接近 Markdown 的语法描述图形。下面这段文本表示：提交变更后运行测试，通过则更新文档，失败则修复并重测。

flowchart LR
A[提交变更] --> B[运行测试]
B --> C{测试通过?}
C -- 是 --> D[更新文档]
C -- 否 --> E[修复问题]
E --> B

flowchart LR 指定从左到右排列；方括号里是节点上显示的文字，箭头连接步骤。它不是从现有文档里提取流程，而是把你写下的流程定义画出来。

加一道复核，图怎样变

现在要求“更新文档”后再由同事复核。在源码末尾补一行 D --> F[人工复核]，预览中就出现从“更新文档”指向“人工复核”的新节点。Everwind 的案例测评页把源码和预览放在一起，下面是加入这一步后的实际画面。

改变的是图的文本定义，因此版本库也能显示这次增加了哪条连线。图会随着这段定义更新，但若团队只改了旁边的说明、代码或实际流程，Mermaid 不会主动发现差异。

放进技术文档

第一次尝试，可以先在官方 Live Editor 的 Code 区粘贴上面的文本，确认右侧 Preview 显示正确，再按真实流程增加或删除节点。随后把同一段内容放进支持 Mermaid 的 Markdown 代码围栏，语言标记写 mermaid，检查目标平台的预览结果。

以后流程变了，修改文档中的图形源码，并检查分支条件和节点含义，再和说明文字一起提交。GitHub 支持渲染这种围栏；如果目标平台不支持，可以从 Live Editor 导出 SVG 或 PNG，但那张静态图片以后仍需重新导出和替换。

它不能替你核对流程

Mermaid 核对的是语法，无法判断“测试通过”后是否真的该直接更新文档，也不会读取提交记录生成正确流程。维护者仍要确认流程是否与系统一致，审阅改动，并在最终发布的平台检查图形显示。

Mermaid 核心项目采用 MIT 许可证。本文案例使用 12.0.0 在浏览器中验证源码修改、预览更新和语法错误提示；换一个文档平台或 Mermaid 版本，先用一张小图确认围栏渲染与导出效果，再决定是否把更多流程图迁进去。