Markdown 中如何绘制图表

图表可以一直是文本：可在 Git diff 中审阅、可快速修改，只在读者需要时渲染成图形。本篇逐字符讲清围栏、类型声明、节点、箭头、标签和关系符号。

MarkIOY Team · 2026 年 8 月 12 日 · 约 24 分钟阅读

从 Mermaid 代码围栏开始

Mermaid 图表使用语言标签为 mermaid 的代码围栏。开头三个反引号表示“开始原样代码”，紧随的 mermaid 选择渲染器，结尾三个反引号结束代码块；围栏中的第一行声明图表类型。它是源码而不是图片，因此可以和解释它的文档一起检索、审阅和修改。

```mermaid
flowchart LR
  A[起草] --> B[评审]
  B --> C[发布]
```

把 flowchart LR 拆开看：flowchart 选择流程图语法，一个空格分开设置，LR 表示从左到右。TD 表示从上到下，RL 表示从右到左，BT 表示从下到上。一张小图只选一个方向。缩进主要服务于人类阅读，但嵌套内容请统一使用两个空格。

常用图表类型与语法

流程图：表达步骤与决策

```mermaid
flowchart TD
  A[打开文档] --> B{可以发布了吗？}
  B -- 是 --> C[导出]
  B -- 否 --> D[继续编辑]
  D --> B
```

方括号表示步骤，花括号表示决策。ID 使用 Review 这类短而稳定的英文式名称，标签可以用自然语言。每个节点只放一个意思；流程图超过约十个节点时，应按职责或层级拆分。同一 ID 在后续行再次出现时，指向的是同一个节点。

时序图：表达交互发生的顺序

```mermaid
sequenceDiagram
  participant 写作者
  participant 编辑器
  participant 文件
  写作者->>编辑器: 编辑 Markdown
  编辑器->>文件: 本地保存
  文件-->>编辑器: 返回更新内容
  编辑器-->>写作者: 渲染预览
```

participant 行创建一条命名生命线。在 写作者->>编辑器: 编辑 Markdown 中，写作者 是发送者，->> 是实线请求箭头，编辑器 是接收者，冒号分开箭头和消息文字，后面是消息标签。-->> 是虚线响应；需要空心箭头时用 --> 或 ->。时序图解释沟通发生的顺序，不能单独代替完整接口约定。

类图：表达概念与关系

```mermaid
classDiagram
  class Document {
    +String markdown
    +save()
  }
  class Workspace {
    +open(Document)
  }
  Workspace "1" o-- "many" Document
```

在 class Document { ... } 中，花括号包住一个类体。开头的 + 表示 public；String markdown 是属性，+save() 是方法。Workspace "1" o-- "many" Document 中，引号内是数量，o-- 是聚合关系（整体拥有部分），两侧是类名。先表达概念，不要试图复制每一个源代码成员。

状态图：表达生命周期与转换

```mermaid
stateDiagram-v2
  [*] --> 草稿
  草稿 --> 评审: 提交
  评审 --> 草稿: 修改
  评审 --> 已发布: 通过
  已发布 --> [*]
```

[*] 是 Mermaid 的开始或结束标记。每行从左向右读：草稿 --> 评审: 提交 表示从“草稿”转到“评审”，冒号后是触发转换的事件。状态图适合表达互斥的生命周期状态，不适合罗列一堆普通待办。

实体关系图：表达数据模型

```mermaid
erDiagram
  WORKSPACE ||--o{ DOCUMENT : contains
  DOCUMENT ||--o{ REVISION : has
  WORKSPACE {
    string name
  }
  DOCUMENT {
    string title
    string markdown
  }
```

ER 图中的实体通常使用大写名字。WORKSPACE ||--o{ DOCUMENT : contains 中，实体旁符号表达基数：|| 是恰好一个，o{ 是零个或多个，冒号开始关系标签。属性写在花括号里，格式为 类型 名称。先画关系，再补读者理解所需的少量属性。

计划与概览类图表

```mermaid
gantt
  title 发布计划
  dateFormat  YYYY-MM-DD
  section 写作
  草稿     :done, 2026-08-01, 3d
  评审     :active, 2026-08-04, 2d
  发布     :milestone, 2026-08-06, 0d
```

甘特图任务行 草稿 :done, 2026-08-01, 3d 中，冒号分开可见任务名和元数据；done 是状态，逗号分开字段，ISO 日期是开始时间，3d 是三天。所有日期必须符合已声明的 dateFormat。milestone 没有时长，所以写 0d。

较完整的样例：文档流转

架构图可用 subgraph 把相关节点分组。该单词开始一组，后面的标签给边界命名，缩进让组内代码易读，end 关闭分组。标签说明意图，箭头说明数据或控制的方向；这比把每个内部细节都画上去更有用。

```mermaid
flowchart LR
  Writer[写作者] --> Web[MarkIOY Web]
  subgraph Browser[浏览器]
    Web --> Source[Markdown 源码]
    Source --> Preview[渲染预览]
  end
  Source --> Download[本地 .md 文件]
  Download --> Git[Git 或其他编辑器]
```

先从这个概念层级开始。只有当另一类读者确实需要时，再添加一张说明技术依赖的图。一张图只回答一个问题。

兼容性与最佳实践

1. 在最终发布工具中检查支持

各产品和版本对 Mermaid 的支持并不一致。MarkIOY、许多文档工具和静态站点配置可以渲染它；普通 Markdown 查看器可能只显示源码围栏。请在最终目标中预览，并写一小段文字说明，确保不渲染时文档仍然能被理解。

2. 优先使用稳定、朴素的语法

节点 ID 使用 Editor 这样的简单名称，面向读者的文字放在方括号中。标签包含标点时按解析器要求加引号；不要把 end 这类保留字当作 ID。除非确认所有目标渲染器都支持，否则不要依赖主题、定制 CSS、点击事件或最新语法。

3. 让源码也保持可读

统一缩进，每行只写一个关系，并使用有意义的 ID。标签保持短，把详细解释写在图表旁的正文中。图表源码也会进入代码审阅与 AI 检索；可读的源码比密集的箭头块更容易修改。渲染失败时依次检查：开闭反引号、mermaid 语言标签、图表类型声明、括号/花括号是否配对、箭头拼写。

4. 只有在理由明确时才选择其他格式

团队已有 PlantUML 渲染器时可使用 PlantUML；Graphviz DOT 擅长图布局；手工绘制的插画则可能更适合 SVG 或图片链接。但它们并非 Markdown 核心能力：请放进带标签的代码围栏或链接生成结果，并说明渲染所需工具。

5. 让图表可访问

介绍图表时先写出结论，而不是只给标题；不要只靠颜色区分状态；重要关系要在附近文本中重复说明。图表应澄清文字，而不能承载唯一的决策信息。