mermaid 代码块
Mermaid 图表放在围栏代码块中。围栏是三个反引号。在起始围栏后,把 mermaid 写作语言:
```mermaid
flowchart LR
A --> B
```
代码块内的第一行说明这是哪一种图表。这里是 flowchart LR。这一行之后的所有内容都是对图表的描述。
以 %% 开头的行是注释。阅读器会忽略它们。
示例 1:带判断的流程图
```mermaid
flowchart TD
Start[Write the note] --> Check{Is it clear?}
Check -->|Yes| Publish[Share it]
Check -->|No| Edit[Rewrite it]
Edit --> Check
```
怎么读它:
flowchart TD表示从上到下。从左到右请使用LR。也可以用graph这个词来代替flowchart。Start[Write the note]会生成一个方框。Start是简短的名称,括号中的文字是标签。- 花括号
{ }会生成判断形状,即菱形。 -->会画出一个箭头。竖线之间的文字,如|Yes|,是箭头的标签。
示例 2:时序图
时序图按顺序显示谁在和谁交流。
```mermaid
sequenceDiagram
participant U as User
participant S as Server
U->>S: Open the page
S-->>U: Send the page
U->>S: Log in
S-->>U: Welcome
```
participant U as User会创建一个名为 User 的列。简短的名称是U。->>是实线箭头。-->>是虚线箭头,常用于回复。- 冒号后面的文字是消息。
- 消息按你书写的顺序,从上到下绘制。
示例 3:饼图
```mermaid
pie title Time spent on a project
"Writing" : 40
"Reading" : 25
"Meetings" : 15
"Other" : 20
```
每个扇区由一个带引号的标签、一个冒号和一个数字组成。数字必须大于零。
其他图表类型
Mermaid 还能绘制更多种类。常见的有:
- 甘特图: 时间线上的任务。
- 类图: 代码中的类以及它们如何关联。
- 状态图: 某个事物的各种状态,以及它在状态之间如何转换。
- 实体关系图: 数据库表和它们之间的联系。
- 用户旅程: 一个人所经历的步骤。
- 思维导图: 从一个中心发散出去的想法。
- 时间线: 按日期顺序排列的事件。
- Git 图: 分支和提交。
每种类型都有自己的首个关键字和自己的规则。Mermaid 文档为每一种类型都提供了一个页面。
Mermaid 图表在哪里绘制
GitHub 会绘制 Markdown 文件、议题、讨论、拉取请求和 wiki 中的 Mermaid 代码块。你只需要 mermaid 代码块。许多 Markdown 编辑器和笔记应用也支持 Mermaid,但并非全部。
当阅读器不支持 Mermaid 时,它通常会把该代码块当作普通代码处理。你看到的是自己写的文字,而不是一幅图。什么都没有丢失,只是没有绘制出来。
常见错误
- 一个小小的笔误会让整幅图失效。 未知或拼错的关键字会导致它无法绘制。如果看到错误或纯文本,请先检查第一行和箭头。
- 标签中的特殊字符。 括号及类似字符可能会让解析器混淆。请把标签放进引号中:
A["Save (draft)"]。 - 流程图中的
end一词。 小写的end会破坏流程图。请写成End或END,或者把这个词放进引号中。它在时序图中也可能引起问题。 - 围栏不对。 反引号后面的语言必须是
mermaid。否则,阅读器看到的就是普通代码块。
缩进不是必需的。大多数人缩进图表内的行,只是因为这样更易读。
AI 聊天和智能体会写 Mermaid
AI 聊天和编程智能体常常在计划、规格说明和设计笔记中放入 Mermaid。流程图是展示步骤的快捷方式。时序图则显示系统的各个部分如何交流。
如果聊天给了你一幅图表,请把整个代码块(包括围栏)复制到你的 Markdown 文件中。如果图表没有绘制出来,请对照上面的错误来检查。简短的标签,以及每幅图只表达一个想法,会让文字更容易修改。
阅读 Mermaid 图表
PilcrowMD 在 Android 和 Mac 上绘制 Mermaid 图表,无需联网。在 Android 上,点按图表即可全屏查看。在 Mac 上,快速查看、比较和 PDF 显示的是代码块,而不是图片。
常见问题
写 Mermaid 需要安装什么吗? 不需要。你在代码块中写纯文本。你只需要一个能绘制它的阅读器。
为什么我看到的是代码,而不是图表? 要么是阅读器不支持 Mermaid,要么是图表有语法错误。请检查代码块是否以 mermaid 开头,以及第一行是否写了真实存在的图表类型。
我能改变图表的外观吗? 能。Mermaid 提供了颜色、形状和布局的选项。请先从默认设置开始,对大多数笔记来说已经够用。
Mac 上同样可用: PilcrowMD Mac 版(测试版)