Markdown画图——Mermaid

用户608308929047
0 阅读5分钟

前言

对于文档，一张形象的图片对于理解都是事半功倍的效果。对于没有画图美化经验（比如：本作者）的人来说，只关注内容，让工具自动排版，往往是省时省力的做法，Mermaid是其中一款不错的选择。

定义

Mermaid是一种基于文本的图表生成工具，使用类似 Markdown 的语法帮助开发者用代码描述图表结构。它被广泛用于绘制流程图、时序图、甘特图等。Mermaid 集成在许多文档工具中，如 Markdown 编辑器、Typora、GitBook、Docusaurus 等，也支持在网页中直接嵌入渲染。

Mermaid 的语法结构通常包裹在代码块中，通过特定的关键字 mermaid 声明。以下是常见的一些语法类型和使用示例：

语法与示例

1. 流程图 (Flowcharts)

流程图用于描述流程的走向，使用 graph 关键字定义:

代码

graph LR
    A[开始] --> B{条件判断}
    B -->|是| C[执行动作]
    B -->|否| D[结束]
    C --> D
  • graph: 声明流程图结构。
  • TD: 表示图表方向 —— Top to Down（上下方向，Direction 有多种选项）
    • TD：Top Down（从上到下）
    • LR：Left to Right（从右到左）
    • TB：Top to Bottom（类似 TD）
    • BT：Bottom to Top（从下向上）
    • RL：Right to Left（从左向右）

节点、连接线和标签：

  • 方括号 []：表示 默认 节点
  • 花括号 {}：表示 带边界的 条件节点（条件/判断框）
  • 圆括号 ()：表示 子流程/普通节点
  • -->：箭头连接线，表示流程方向
  • |...|：连接线上描述信息（如条件判断）

效果图

graph LR
    A[开始] --> B{条件判断}
    B -->|是| C[执行动作]
    B -->|否| D[结束]
    C --> D

2. 时序图（Sequence Diagrams）

时序图描述系统的交互过程，常用于展示组件之间消息的顺序，用 sequenceDiagram 开始

代码

sequenceDiagram
    participant 用户
    participant 浏览器
    participant API
    participant 数据库
    
    用户->>浏览器: 输入网址
    浏览器->>API: 发送请求
    API->>数据库: 查询数据
    数据库-->>API: 返回结果
    API-->>浏览器: 返回响应
    浏览器-->>用户: 显示页面
  • participant：定义参与对象，as 可定义别名，让脚本简短
  • ->>：实线箭头
  • -->>：虚线箭头
  • activate, deactivate：激活与取消激活组件生命线

效果图


sequenceDiagram
    participant 用户
    participant 浏览器
    participant API
    participant 数据库
    
    用户->>浏览器: 输入网址
    浏览器->>API: 发送请求
    API->>数据库: 查询数据
    数据库-->>API: 返回结果
    API-->>浏览器: 返回响应
    浏览器-->>用户: 显示页面

3. 甘特图（Gantt）

甘特图用于项目管理或展示时间进度，用 gantt 开始

代码

gantt
    title 项目时间表
    dateFormat  YYYY-MM-DD
    section 引入阶段
    需求分析               :a1, 2024-01-01, 30d
    设计                   :a2, after a1, 40d
    section 开发阶段
    前端开发               :a3, 2024-02-01, 60d
    后端开发               :a4, 2024-02-15, 60d
    section 测试阶段
    单元测试               :a5, after a3, 10d
    系统测试               :a6, after a4, 20d
  • title: 定义标题
  • dateFormat: 定义时间格式
  • section：定义不同阶段
  • after: 表示基于前一个任务的时序
  • 30d / 2w: 表示时间长度（day/week）
  • :a1: 节点 ID 可用于任务间依赖（子图逻辑）

效果图

gantt
    title 项目时间表
    dateFormat  YYYY-MM-DD
    section 引入阶段
    需求分析               :a1, 2024-01-01, 30d
    设计                   :a2, after a1, 40d
    section 开发阶段
    前端开发               :a3, 2024-02-01, 60d
    后端开发               :a4, 2024-02-15, 60d
    section 测试阶段
    单元测试               :a5, after a3, 10d
    系统测试               :a6, after a4, 20d

4. 类图（Class Diagrams）

用于绘制面向对象设计的类图，用 classDiagram 开始

代码

classDiagram
    class Student {
        -String name
        +public method()
    }
 
    class School {
        -String address
    }
 
    Student --> "0..*" School : belongs to
  • class: 声明类以及其内部属性
  • {} ：中的内容是类结构（+ 公有，- 私有，~ 受保护）
  • --> ：表示类之间的关联关系
  • 0..* ：在箭头两边添加基数（如 0..*）表示类之间的关联数量

效果图

classDiagram
    class Student {
        -String name
        +public method()
    }
 
    class School {
        -String address
    }
 
    Student --> "0..*" School : belongs to

5. 状态图 (State Diagrams)

状态图用于表达系统状态及其转换情况，用 stateDiagram 开始

代码

stateDiagram
    [*] --> 未启动
    未启动 --> 运行中: 开始
    运行中 --> 已完成: 完成
    已完成 --> [*]: 系统结束
  • [*] 代表初始状态或结束状态。
  • --> 表示状态转换的箭头。
  • : 注释：标注操作或消息触发条件。

效果图

stateDiagram
    [*] --> 未启动
    未启动 --> 运行中: 开始
    运行中 --> 已完成: 完成
    已完成 --> [*]: 系统结束

复杂声明以及图示

stateDiagram
    state If_Success {
        [*] --> Ok
        Ok --> [*]
    }

    state If_Failed {
        [*] --> Error
        Error --> [*]
    }

    Start --> If_Success: 正确输入
    Start --> If_Failed: 错误输入

stateDiagram
    state If_Success {
        [*] --> Ok
        Ok --> [*]
    }

    state If_Failed {
        [*] --> Error
        Error --> [*]
    }

    Start --> If_Success: 正确输入
    Start --> If_Failed: 错误输入
  • state ... {}：构建子状态组

6. Git 图（Git Graph）

用于表达版本控制中 Git 分支的拓扑结构，以 gitGraph 开始

gitGraph
    commit id: "init"
    commit
    branch dev
    commit
    commit
    checkout main
    merge dev
  • gitGraph：定义为 Git 图。
  • commit：表示一次提交。
  • id: 给提交打上唯一标识符（任意字符串）
  • branch：新建分支。
  • checkout：切换到该分支。
  • merge：将分支合并。

效果图

gitGraph
    commit id: "init"
    commit
    branch dev
    commit
    commit
    checkout main
    merge dev

常用保留符号及注意事项

符号用途说明
-->箭头流向流程图中最常见连接线表达方式
<-->双向箭头表示两个节点/状态可以双向跳转
=>粗节点线用于某些流程图表示重要流程，如高亮分支
---普通横线连接A --- B 只连接两节点但未定义流向（不推荐常规路径）
:节点标注 或 时间定义:a1 用于节点命名，如：A[a] :a1
|分段条件/分支标签|是|、|失败| 可添加判断说明
%%注释符%% 这是一个注释
"文本域引用"标签名称" 更可靠地匹配中文或含空格内容
{}类图或状态图的组内容类图属性分组，状态嵌套都会使用
[]表示流程图中的节点（非条件）示例：A[流程] --> B
{}流程图中的节点（判断类）示例：B{判断}
()子图内容定义（较少见）特殊类型节点，例如模块调用、自定义节点
as给参与方起别名例如：participant P as Prometheus
classDef定义类样式用于定义图中节点的显示风格
class将类样式赋给某个节点例如：class A custom-class
subgraph定义子图区域流程图中划分子结构的语法
[ID]定义节点 ID（不是显示名）成功节点：A[成功] :success_node
since类图中变更标记日期在 UML 类图表示属性从什么版本/日期开始存在

数字、时间、单位标记

符号示例说明
30da1, 2024-01-01, 30d表示持续 30 天
2wa2... 2w表示持续两周
dateFormatYYYY-MM-DD甘特图表示时间的标准格式
section甘特图中的阶段划分用于分段工程项目，例如“研发阶段 / 测试阶段”

尾声

Mermaid 可以让开发者专注于图表内容和逻辑，而不必关注外在的形象，熟悉语法之后画一张图还是挺方便的。

参考来源：Qwen: Qwen3 235B A22B

一家之言，如有谬误，欢迎指正！

avatar
文章
阅读
粉丝