目录

用 Mermaid 画图(Markdown 写法)

Mermaid 是一个“文本转图表”工具:写一段类似 Markdown 的声明式文本,由渲染器把它画成流程图、时序图、类图等。 GitHub、GitLab、Typora、Obsidian、VS Code、Notion 等平台都内置支持,写法基本一致。

本站现状:这个 wiki 目前没有安装 Mermaid 渲染插件(站点中不存在 lib/plugins/mermaid 目录), 因此下文的示例在本站只会以代码形式显示,不会画成图。想让它真正渲染,需要先安装 DokuWiki 的 mermaid 插件; 装好之后本页的语法即可直接使用。

一、最小例子

flowchart TD
    A[开始] --> B{条件判断}
    B -->|是| C[处理一]
    B -->|否| D[处理二]
    C --> E[结束]
    D --> E

解读:

二、两条使用路径

Markdown 系平台(GitHub / Typora / Obsidian / VS Code…):用围栏代码块,语言标记写 mermaid。 围栏的写法是:首尾各一行连续三个反引号,首行三个反引号后面紧跟语言标记 mermaid(本页为避免把页面自身的解析带偏,示例只展示围栏里面的内容):

flowchart LR
    client[客户端] --> gate[网关]
    gate --> db[(数据库)]

DokuWiki(安装 mermaid 插件之后):可以用 <mermaid> 标签,也可以用同样的围栏写法:

<mermaid>
flowchart LR
    client[客户端] --> gate[网关]
</mermaid>

共同要点:第一行必须是图类型声明,否则渲染器不知道要画什么。

三、常用图类型

第一行声明 画出来是什么
flowchart TD / graph TD 流程图(最常用)
sequenceDiagram 时序图(参与者之间来回的消息)
classDiagram 类图(UML 类、属性、继承)
stateDiagram-v2 状态机 / 状态流转
erDiagram ER 图(数据库表与关系)
gantt 甘特图(排期)
pie 饼图
mindmap 思维导图(需要较新版本)
gitGraph Git 分支图
journey 用户旅程图

四、流程图语法

节点形状

id1[矩形]         id2(圆角)         id3([胶囊])       id4[[子程序]]
id5[(数据库)]     id6((圆形))       id7{菱形判断}     id8{{六边形}}
id9[/平行四边形/] id10[\反平行四边形\]  id11[/梯形\]  id12[\倒梯形/]

id1 这类只是标识符,页面上显示的是括号里的文字;后面再用 id1 --> id2 引用它即可。

连线

A --> B          实线箭头
A --- B          实线、无箭头
A -.-> B         虚线箭头
A ==> B          粗箭头
A -->|文字| B     带标签(推荐写法)
A -- 文字 --> B   带标签(另一种写法)
A <--> B         双向箭头

一条连线上要“上下各有一个值”

Mermaid 的一条连线只有一个标签,没有“线上方一个值、线下方一个值”的官方语法。实践中用下面两种近似写法:

写法一:标签内换行,让同一条连线的标签排成两行,视觉上就是上下两个值:

flowchart LR
    A -->|"上行值<br>下行值"| B

也可以写成 A -- 上行值<br>下行值 --> B。<br> 和 <br/> 都可用; 文字含空格、括号、逗号时建议整体加双引号。 注意:换行只是让标签文字变成两行,两行相对线条的确切位置由渲染器排版决定,无法精确指定哪行在线上、哪行在线下。

写法二:画两条同向连线,每条各带一个标签。这样两个值会稳定地分列在两条线旁,最容易做出“上下两个值”的效果:

flowchart LR
    A -->|上行值| B
    A -.->|下行值| B

建议用虚实线区分两条线,或让两条线指向不同形状的节点,避免标签互相压住。

时序图没有“箭头上下两个值”的概念,一条消息只有一行文字(U->>S: 提交表单); 需要额外说明时用 Note over U,S: 说明文字,它会画在参与者之间的横框里。

文字含特殊字符要加引号

文字里有空格、括号、逗号、冒号时,用双引号把显示文字包起来,否则容易解析失败:

A["带(括号)的说明"] --> B["Hello, World"]

子图

flowchart TD
    subgraph 前端
        A[页面] --> B[组件]
    end
    subgraph 后端
        C[接口] --> D[(数据库)]
    end
    B --> C

给节点上色

flowchart TD
    A[成功] --> B[失败]
    classDef ok fill:#dcfce7,stroke:#16a34a
    classDef bad fill:#fee2e2,stroke:#dc2626
    class A ok
    class B bad

注释

以两个百分号开头的行是注释,不会被画出来:

%% 这是一行注释
flowchart TD
    A --> B

五、其它图类型速记

时序图

sequenceDiagram
    participant U as 用户
    participant S as 服务端
    U->>S: 提交表单
    S-->>U: 返回结果
    Note over U,S: 一次请求往返

状态图

stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付: 付款成功
    已支付 --> [*]

类图

classDiagram
    class Animal {
        +String name
        +eat() void
    }
    class Dog
    Animal <|-- Dog

甘特图

gantt
    title 项目排期
    dateFormat YYYY-MM-DD
    section 设计
    需求调研 :a1, 2024-01-01, 7d
    section 开发
    编码     :a2, after a1, 14d

饼图

pie title 流量来源
    "搜索" : 45
    "直达" : 30
    "社交" : 25

ER 图

erDiagram
    USER ||--o{ ORDER : 下单
    ORDER ||--|{ ITEM : 包含
    USER {
        string name
        string email
    }

六、常见坑

七、本站可选方案

  • 要真正渲染 Mermaid:安装 DokuWiki 的 mermaid 插件,装好后本页语法即可直接使用。
  • 只想画思维导图:本站已支持 mdk 代码块(markmap 渲染),无需额外插件。