第3章 让文档会画图

第3章 让文档会画图

章节摘要：流程、架构、时序、层次——这些信息用文字描述事倍功半，画成图则一眼即懂。本章练三种画图路数：Mermaid 围栏图（流程/时序/状态/甘特）、内联 SVG（架构总览、对比矩阵这类自由布局）、以及内嵌 HTML 的能力边界。学完你的文档就能"图文并茂"，而且是源码即图、随版本管理一起演进的图。

学习目标

阅读完本章，你应当能够：

1. 用 Mermaid 写出流程图、时序图、状态图和甘特图，并避开标签符号禁忌。
2. 判断一张图该用 Mermaid 还是 SVG，掌握"svg 围栏"的写法要素。
3. 理解内嵌 HTML 的能与不能，知道什么时候该退回纯 Markdown。

核心概念速览

图是"用空间表达关系"的语言：箭头说依赖，位置说层级，颜色说类别。

子章节导航

3.1 Mermaid：流程图、时序图与甘特图

四种常用图型逐个上手，语法禁忌清单一次记牢。

3.2 用内联 SVG 画架构图

Mermaid 表达不了的自由布局——分层架构、对比矩阵、时间线——交给 SVG。

3.3 内嵌 HTML 的能力与边界

Markdown 里的 HTML 逃生舱口在哪里，什么时候不该用它。

子章节之间的逻辑关系

三节是一条能力递进的链条：

固定范式图（Mermaid） ──覆盖七八成画图需求
        │ 不够自由时
自由布局图（SVG）    ──补齐架构/矩阵/标注
        │ 仍不够时
HTML 逃生舱          ──最后的手段，代价是可移植性
​

顺序也即优先级：能用 Mermaid 就不手画 SVG，能画 SVG 就不写 HTML——越往后可移植性越差、维护成本越高。

前置知识与后续延伸

• 前置：围栏代码块（1.5 节）——Mermaid 与 SVG 本质都是特殊围栏。
• 为后续铺垫：本章图件依赖平台渲染器支持，第 4 章讲方言差异、第 5 章讲渲染器选型时会回到"图为什么没显示"这个问题；第 6 章排错清单也包含图件项。

图文分工的章法

本章最后补一条贯穿三种路数的章法：图与正文的分工。图不解释自己，正文不复述图——图负责结构与关系的第一眼印象，正文负责图给不了的细节与理由。两种典型失衡都要避免：一是"孤儿图"，正文从头到尾没提到那张图，读者不知道该拿它干什么，每张图至少要有一句"如图所示，某结论"的锚定；二是"复读图"，正文把图的每个节点挨个讲一遍，等于用两种介质说了同一句话，正确做法是只讲图背后的依据与取舍。评审文档里的图时，删掉图问一句"正文还成立吗"、删掉正文问一句"图还看得懂吗"，两个问题都答"是"，图文分工就是健康的。这条章法配合 3.1 的选型纪律与 3.2 的网格规划，画图这件事就从"有感而发"变成有章可循的工程。

本章还有一条与第 5 章直接衔接的实际结论：三种画图路数的维护成本排序大致是 Mermaid 最低、SVG 居中、图片最高——Mermaid 改一行源码即改图，SVG 改坐标，图片要重出图重导出。技术选型时除了"哪条路能表达"，还要问"这块内容未来会改多少次"：频繁演进的架构选 Mermaid 或 SVG，一次性存档的截图才轮到图片。把表达力与维护成本两个维度一起考虑，是本章三节在你手里合为一体的标志。

顺带回答一个本章高频疑问："先学哪条路？"按使用频率，答案是 Mermaid 优先——分支、调用、状态、工期四类问题日常最多，性价比最高；SVG 在你需要第三张对位比较图或精确标注图时再学不迟；内嵌 HTML 则随时按需查用即可。把精力投给出现频率最高的路，是学习路线与写作纪律共用的那条朴素原则。