Markdown 中的 Mermaid 图表

Mermaid 是一种用文字绘制图表的方式。你写几行简短的文字,支持 Mermaid 的阅读器就会把它们变成一幅图:流程图、时间线、图表。

你可以把图表放在普通的 Markdown 文件里。不需要导出图片,也不需要打开绘图工具。要修改图表,改文字就行。

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
```

怎么读它:

示例 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
```

示例 3:饼图

```mermaid
pie title Time spent on a project
    "Writing" : 40
    "Reading" : 25
    "Meetings" : 15
    "Other" : 20
```

每个扇区由一个带引号的标签、一个冒号和一个数字组成。数字必须大于零。

其他图表类型

Mermaid 还能绘制更多种类。常见的有:

每种类型都有自己的首个关键字和自己的规则。Mermaid 文档为每一种类型都提供了一个页面。

Mermaid 图表在哪里绘制

GitHub 会绘制 Markdown 文件、议题、讨论、拉取请求和 wiki 中的 Mermaid 代码块。你只需要 mermaid 代码块。许多 Markdown 编辑器和笔记应用也支持 Mermaid,但并非全部。

当阅读器不支持 Mermaid 时,它通常会把该代码块当作普通代码处理。你看到的是自己写的文字,而不是一幅图。什么都没有丢失,只是没有绘制出来。

常见错误

缩进不是必需的。大多数人缩进图表内的行,只是因为这样更易读。

AI 聊天和智能体会写 Mermaid

AI 聊天和编程智能体常常在计划、规格说明和设计笔记中放入 Mermaid。流程图是展示步骤的快捷方式。时序图则显示系统的各个部分如何交流。

如果聊天给了你一幅图表,请把整个代码块(包括围栏)复制到你的 Markdown 文件中。如果图表没有绘制出来,请对照上面的错误来检查。简短的标签,以及每幅图只表达一个想法,会让文字更容易修改。

阅读 Mermaid 图表

PilcrowMD 在 Android 和 Mac 上绘制 Mermaid 图表,无需联网。在 Android 上,点按图表即可全屏查看。在 Mac 上,快速查看、比较和 PDF 显示的是代码块,而不是图片。

常见问题

写 Mermaid 需要安装什么吗? 不需要。你在代码块中写纯文本。你只需要一个能绘制它的阅读器。

为什么我看到的是代码,而不是图表? 要么是阅读器不支持 Mermaid,要么是图表有语法错误。请检查代码块是否以 mermaid 开头,以及第一行是否写了真实存在的图表类型。

我能改变图表的外观吗? 能。Mermaid 提供了颜色、形状和布局的选项。请先从默认设置开始,对大多数笔记来说已经够用。

Mac 上同样可用: PilcrowMD Mac 版(测试版)