第一部分：Mermaid 基础入门

第1章：初识 Mermaid：图表即代码

1.1 Mermaid 的核心哲学

在动手绘制第一个图表之前，我们需要先理解 Mermaid 背后的“大思想”，这能帮助你更好地掌握它。

1.1.1 什么是“图表即代码” (Diagrams as Code)

第一步：核心理念

“图表即代码”的核心理念是：我们不再使用鼠标去拖拽、对齐和美化图形元素，而是像写代码一样，用纯文本来描述图表的结构和关系。

第二步：一个简单的比喻

• 传统方式：就像用积木手动搭建一座房子。你需要亲手去挑选方块、圆柱，然后小心翼翼地把它们堆叠起来。

• Mermaid方式：你只需要写一份建筑设计图（纯文本代码），描述“地基上有一个方块，方块上有一个圆柱”。然后，一个神奇的“自动化施工机器人”（Mermaid渲染引擎）会自动根据你的设计图，瞬间为你建好这座房子。

第三步：最终结果

你写的这份纯文本“设计图”，会被自动地、漂亮地渲染成一张可视化的图表（如流程图、时序图等）。

1.1.2 与传统绘图工具的对比 (Visio, Draw.io 等)

第一步：回顾传统工具的体验

想象一下你用Visio或Draw.io画一个复杂的流程图：

1. 你从左边的工具栏拖出一个矩形。

2. 再拖出另一个矩形。

3. 你找到箭头工具，小心地从第一个矩形的连接点拉到第二个矩形上。

4. 如果你想在中间加一个步骤，天哪！你必须手动移动后面的所有图形和连接线，重新对齐，非常繁琐。

第二步：传统工具的痛点

• 维护困难：修改一个复杂的图表，就像在做“外科手术”，耗时耗力。

• 无法追踪变更：你很难清晰地看出图表的两个版本之间，到底修改了什么。

• 风格不一：团队协作时，每个人做出的图表颜色、字体、大小都可能不一样，显得很混乱。

第三步：Mermaid如何解决这些痛点

• 维护轻松：想在流程中间加一个步骤？只需要在文本中增加一行代码 C --> D，整个图表会自动重新布局，无需任何手动调整。

• 变更清晰：因为图表是纯文本，你可以用Git等版本控制工具，清晰地看到每一次修改，比如“删除了A到B的箭头，增加了A到C的箭头”。

• 风格统一：图表的外观由主题和样式统一控制，保证了团队输出的所有图表都专业且一致。

---

1.2 Mermaid 的核心优势

基于“图表即代码”的哲学，Mermaid带来了四个巨大的好处。

1.2.1 便于版本控制 (与 Git 协同工作)

第一步：理解Git的工作原理

Git是一个版本控制工具，它最擅长的是追踪文本文件的每一次修改。

第二步：传统图表的困境

传统绘图工具保存的是二进制文件（如.vsdx）。Git只能告诉你“这个文件被修改了”，但无法告诉你内部到底哪里被修改了。

第三步：Mermaid与Git的完美结合

因为Mermaid图表是纯文本，所以你可以像管理代码一样管理它。

Diff

# 假设这是 `git diff` 的输出
- A --> B --> C
+ A --> NEW_STEP --> B --> C

你可以清晰地看到，这次修改只是在A和B之间增加了一个NEW_STEP。这在团队协作和代码审查（Code Review）中极其有用。

1.2.2 易于编辑与维护 (纯文本驱动)

第一步：编辑速度

对于熟悉键盘的人来说，打字通常比频繁地在鼠标和键盘之间切换、点击和拖拽要快得多。

第二步：利用代码编辑器的强大功能

你可以用你最喜欢的代码编辑器（如VS Code）来编写Mermaid，并享受它带来的所有便利：

• 查找和替换：一键修改图表中所有相同的文本。

• 多光标编辑：同时修改多个节点。

• 代码片段：保存常用的图表模板。

第三步：修改的便捷性

• 想修改一个节点的文字？—— 找到那一行，直接改。

• 想改变一个箭头的方向？—— 把 --> 改成 <--。

• 想删除一个节点和它的连接？—— 直接删除那几行文本。 这一切都非常快速和精确。

1.2.3 保持风格一致性

第一步：分离“内容”与“表现”

Mermaid让你能够专注于图表的逻辑和内容（你写的文本），而将外观和样式（最终渲染的样子）分离出去。

第二步：主题(Theme)的力量

图表最终的外观由一个“主题”来控制，就像网站的CSS一样。这意味着：

• 你可以在不修改任何图表逻辑的情况下，通过切换主题（比如从default切换到dark），来改变所有图表的外观。

• 团队可以共享一套自定义的主题，确保所有人创建的图表风格都完全统一。

1.2.4 强大的生态系统与集成能力

第一步：Mermaid无处不在

Mermaid的成功，很大程度上因为它被集成到了无数开发者和写作者日常使用的工具中。

第二步：就地取材，无需切换工具

你可以在你正在使用的工具里直接编写和渲染图表，例如：

• 在项目的README.md文件中解释你的架构。

• 在你的个人笔记应用中梳理你的思路。

• 在公司的知识库（Wiki）中绘制业务流程。 接下来，我们就看看可以在哪些地方使用它。

---

1.3 搭建 Mermaid 编写环境

好消息是，你几乎不需要“搭建”任何复杂的环境。

1.3.1 零配置：官方在线编辑器 (Mermaid Live Editor)

这是最快、最简单的入门方式。

第一步：打开浏览器

访问网址 mermaid.live

第二步：体验实时编辑

• 你会看到页面被分为两部分。

• 左边的代码区 (Code)，是你输入Mermaid文本的地方。

• 右边的预览区 (Preview)，会实时地根据你输入的代码，渲染出图表的样子。

第三</strong>步：使用它来学习和实验

这个在线编辑器是学习和测试Mermaid语法的最佳场所。

1.3.2 本地桌面：VS Code + 插件

如果你想在自己的电脑上离线编写，VS Code是最佳选择。

第一步：安装VS Code

你的系统是Linux，通常你可以从你的发行版的“软件中心”直接安装，或者从VS Code官网下载对应的安装包（.deb for Debian/Ubuntu, .rpm for Fedora/CentOS）。

第二步：安装Mermaid插件

1. 打开VS Code。

2. 点击左侧边栏的“扩展”（Extensions）图标（像四个方块的标志）。

3. 在搜索框中输入 Mermaid。

4. 找到并安装一个支持预览的插件，例如 Markdown Preview Mermaid Support。

第三步：开始编写

现在，你只需要创建一个Markdown文件（以.md结尾），然后在里面写Mermaid代码块，打开预览窗口，就能看到渲染好的图表了。

1.3.3 云端笔记：Notion, Typora, Obsidian 等

许多现代笔记软件已经原生支持了Mermaid。

第一步：创建一个代码块

在这些应用中，通常你需要先创建一个“代码块” (Code Block)。

第二步：指定语言为 mermaid

在代码块的语言选择菜单中，选择或输入 mermaid。

第三步：编写并欣赏

在你输入完Mermaid代码后，这些应用会自动将其渲染成精美的图表，无缝嵌入在你的笔记中。

1.3.4 代码托管平台：GitHub, GitLab 的原生支持

这对于开发者来说是革命性的功能。

第一步：编辑一个Markdown文件

在你的GitHub或GitLab项目中，编辑任何一个Markdown文件，比如 README.md。

第二步：写入Mermaid代码块

像在本地一样，创建一个语言标记为 mermaid 的代码块。

第三步：保存并查看

当你保存文件后，GitHub/GitLab的网页会直接将这段代码渲染成图表。这意味着你的项目文档可以包含永远和代码同步的、清晰的架构图和流程图。

---

1.4 Mermaid 的基本语法结构

现在，我们来看一下所有Mermaid图表的“开场白”和基本框架。

1.4.1 图表类型声明 (如 graph, sequenceDiagram)

第一步：声明你的意图

任何一段Mermaid代码，必须以图表类型声明开头。这行代码告诉渲染引擎，你接下来要画的是哪一种图。

第二步：常见的类型

• 如果你想画一个流程图，你的代码第一行就是 graph。

• 如果你想画一个时序图，第一行就是 sequenceDiagram。

• 如果你想画一个甘特图，第一行就是 gantt。

好比说：这就像写文章前，你必须先确定文章的体裁是“诗歌”、“散文”还是“小说”。

1.4.2 方向定义 (如 TD, LR)

第一步：为流程图指定方向

紧跟在graph声明之后，你可以定义图表的布局方向。

第二步：常见的方向

• TD 或 TB：Top to Down / Top to Bottom（从上到下），这是默认方向。

• LR：Left to Right（从左到右）。

第三步：看一个例子

代码段

graph LR

这行代码声明了：“接下来是一个流程图，并且它的整体流向是从左到右的。”

1.4.3 代码块的编写与渲染

第一步：使用Markdown代码块

在绝大多数支持Mermaid的平台（如GitHub, VS Code, Notion）中，你都需要将Mermaid代码包裹在一个标准的Markdown代码块里，并指明语言是mermaid。

第二步：观察标准结构

请看下面这个完整的、最小的Mermaid代码块：

Markdown

```mermaid
graph TD
    Start --> Stop
```

• 最外层的 ``` 是Markdown语法，表示这是一个代码块。

• 紧跟着的 mermaid 告诉渲染器：“请用Mermaid引擎来处理这里面的内容”。

• graph TD 是我们学过的类型和方向声明。

• Start --> Stop 是图表的具体内容（我们将在下一章学习）。

第三步：理解渲染过程

最终，整个流程是这样的：你写好这段文本代码块 -> 你正在使用的工具（如GitHub）识别到mermaid标记 -> 它调用Mermaid的渲染引擎 -> 引擎读取你的文本，将其转换为一张SVG格式的矢量图 -> 最后用这张图替换掉你写的代码块，呈现给你一个漂亮的可视化图表。