Mermaid 是一个非常棒的工具，它能让你像写代码一样，用简单的文本来创建漂亮的图表和流程图。对于“小白”来说，它绝对是记录思路、梳理流程的神器。

这篇入门教程将带你轻松掌握 Mermaid 的核心语法，让你能立即上手创建自己的图表。

---

Mermaid 小白入门使用教程

0 节点名称是否需要用双引号包裹 --核心原则

当你无法确定是否需要引号时，最安全的做法是：始终用双引号 " 将节点内容包裹起来。 比如 A["我的节点内容"]。这是一个万无一失的好习惯。

需要引号包裹的特殊字符列表

以下字符在 Mermaid 的语法中有特殊含义，如果它们出现在你的节点文本中，必须使用双引号包裹，否则解析器会混淆，导致渲染失败。

虽然大部分时候带空格的文本不需要引号，但如果你的文本与其他语法元素结合时，可能会产生歧义。例如，如果你的节点ID和节点文本之间没有明确的分隔符，空格可能会导致问题。

始终使用引号可以避免所有这类不确定性。

总结表格

字符/类型	描述	是否必须加引号	示例（正确写法）
( ) { } [ ]	括号类，用于定义节点形状	是，必须	A["文本(带括号)"]
;	分号，语句结束符	是，必须	B["任务A; 任务B"]
end	关键字，结束子图	是，强烈推荐	C["end"]
& < >	HTML 特殊字符	推荐	D["Q&A"] E["a > b"]
包含空格的长文本	普通文本	否，但推荐	F["这是一个带空格的长文本"]

最终建议：

为了代码的健壮性和可读性，养成给所有节点文本加上双引号的习惯。这样你就永远不必去记忆哪些字符是特殊的，从而将注意力集中在图表的逻辑本身。

一、 Mermaid 是什么？

想象一下，你不需要拖动复杂的图形软件，只需要写几行简单的文字，比如：

graph TD;
    A-->B;
    B-->C;

就能自动生成一个流程图：

这就是 Mermaid 的魅力！它是一个基于 JavaScript 的库，能将类似 Markdown 的文本语法解析成各种图表。很多主流的笔记软件和开发工具（如 Typora、Notion、VS Code 插件、GitLab 等）都支持 Mermaid。

二、 核心语法入门：流程图 (Flowchart)

流程图是 Mermaid 中最常用、最基础的图表，我们就从它开始。

1. 图表方向

首先，你需要告诉 Mermaid 你的流程图是哪个方向的。

• graph TD 或 graph TB - 从上到下 (Top to Bottom/Top Down)
• graph LR - 从左到右 (Left to Right)
• graph RL - 从右到左 (Right to Left)
• graph BT - 从下到上 (Bottom to Top)

语法：
第一行总是以 graph 加上方向声明开始，并以分号结束（虽然有时可以省略，但建议养成习惯）。

2. 定义节点 (Nodes)

节点就是流程图中的方框、圆角矩形、圆形等形状。

• 默认形状（矩形）：直接写文字即可。
  • A
• 带文字的节点：如果你的节点文字包含特殊字符或空格，需要用引号。
  • A["这是一个节点"]
• 不同形状的节点：
  • A(圆角矩形)
  • B((圆形))
  • C>不对称矩形]
  • D{菱形}
  • E{{六边形}}

示例：

graph TD;
    Start((开始));
    Step1["步骤一：准备材料"];
    Check{条件判断：材料是否齐全?};
    End((结束));

3. 连接节点 (Links)

连接就是节点之间的箭头。

• 带箭头的实线： -->
• 不带箭头的实线： ---
• 带箭头的虚线： -.->
• 不带箭头的虚线： -.-
• 加粗的箭头： ==>

示例：

graph TD;
    A-->B;      // A 指向 B
    B---C;      // B 和 C 无向连接
    C-.->D;     // C 虚线指向 D
    D==>E;      // D 粗线指向 E

4. 在连接线上添加文字

可以在连接线中间添加描述文字。

• A--文字-->B
• A---|描述文字|B

示例：

5. 综合实例：一个完整的“泡茶”流程图

现在，我们把上面的知识点组合起来，创建一个完整的流程图。

graph TD;
    A((开始)) --> B["准备茶叶和茶具"];
    B --> C{烧开水};
    C -- 水开了 --> D["用开水冲泡茶叶"];
    D --> E((享用香茶));

效果：

---

三、 其他常用图表示例

掌握了流程图，你就掌握了 Mermaid 80% 的精髓。其他图表的语法也遵循类似的逻辑。

1. 序列图 (Sequence Diagram)

用来表示对象之间的交互顺序。

语法核心：

• participant 声明参与者。
• A->>B: 消息内容 表示 A 向 B 发送一个消息。
• activate 和 deactivate 控制生命线的激活状态。
• alt/else 表示选择分支。
• loop 表示循环。

示例：用户登录过程

2. 甘特图 (Gantt Chart)

用于项目管理，展示任务的时间安排。

语法核心：

• title 定义图表标题。
• dateFormat 定义日期格式。
• section 定义任务分组。
• 任务名称 :done/active/crit, 任务ID, 开始时间, 持续时间/结束时间

示例：一个简单的项目计划

---

给小白的建议

1. 从模仿开始：找一些现成的例子，试着修改里面的文字和连接，看看会发生什么变化。
2. 由简到繁：先从最简单的 A–>B 开始，然后逐步增加节点、改变形状、添加判断。
3. 利用在线编辑器：访问 Mermaid 的官方在线编辑器 (https://mermaid.live)，它可以实时预览你的代码效果，非常适合学习和调试。
4. 记住核心语法：
   • 流程图：graph 方向; 节点A --> 节点B;
   • 序列图：participant A; A->>B: 消息;
   • 甘特图：section 组; 任务: 开始时间, 持续时间;

Mermaid 的学习曲线非常平缓，只要你动手尝试，很快就能用它来清晰地表达你的想法了。祝你使用愉快！