Mermaid 使用指南

Mermaid 使用指南

本文档介绍

1. 如何在 VSCode 中配置 Mermaid 语法预览环境，
2. 如何安装 Mermaid CLI，以及如何将 .mmd 文件转换为 PNG 图片。
3. mermaid 语法介绍及示例

---

1. VSCode 配置 Mermaid 预览

1.1 安装插件

在 VSCode 扩展市场搜索并安装以下插件（任选其一即可）：

插件名	扩展 ID	说明
Markdown Preview Mermaid Support	bierner.markdown-mermaid	在 Markdown 预览中渲染 Mermaid 图表（推荐）
Mermaid Preview	vstirbu.vscode-mermaid-preview	直接预览 .mmd 文件

命令行安装：

# 安装 Markdown 预览支持（推荐）
code --install-extension bierner.markdown-mermaid

# 安装 .mmd 文件直接预览
code --install-extension vstirbu.vscode-mermaid-preview

1.2 在 Markdown 中使用 Mermaid

在 .md 文件中使用代码块标注 mermaid，安装插件后可在预览面板（Ctrl+Shift+V）中看到渲染结果：

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> A
```

1.3 直接预览 .mmd 文件

安装 vstirbu.vscode-mermaid-preview 后，打开 .mmd 文件，使用命令面板（Ctrl+Shift+P）执行：

Mermaid: Open Preview to the Side

或右键文件选择 Preview Diagram。

---

2. 安装 Mermaid CLI

Mermaid CLI（mmdc）可将 .mmd 文件批量转换为 PNG、SVG、PDF 等格式。

2.1 前置条件

Mermaid CLI 依赖 Node.js（建议 v16+）：

# 检查 Node.js 版本
node --version

# 若未安装，使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

2.2 全局安装

npm install -g @mermaid-js/mermaid-cli

如果失败可以参考以下步骤方法（国内尝试用下面这个镜像）

或 参考：WSL Ubuntu中安装Mermaid CLI失败解决

    npm install -g @mermaid-js/mermaid-cli --verbose --registry=https://registry.npmmirror.com

如果失败可以这样，或参考步骤2.4：

npm cache clean --force
rm -rf ~/.cache/puppeteer

export PUPPETEER_SKIP_DOWNLOAD=true
# npm install -g @mermaid-js/mermaid-cli --verbose
npm install -g @mermaid-js/mermaid-cli --verbose --registry=https://registry.npmmirror.com

# install chrome manually
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install ./google-chrome-stable_current_amd64.deb
rm google-chrome-stable_current_amd64.deb

# set env
which google-chrome
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome
echo "export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome" >> ~/.bashrc
echo "please reload the env by: source ~/.bashrc"

验证安装：

mmdc --version

2.3 项目本地安装（推荐用于 CI/CD）

# 在项目根目录
npm install --save-dev @mermaid-js/mermaid-cli

# 使用 npx 调用
npx mmdc --version

2.4 Linux 无头浏览器依赖

Mermaid CLI 内部使用 Puppeteer 驱动 Chromium。Linux 服务器上需要安装 Chromium 依赖：

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y chromium-browser

# 如果 Puppeteer 无法找到 Chromium，手动指定路径
export PUPPETEER_EXECUTABLE_PATH=$(which chromium-browser)

---

3. 将 .mmd 文件转换为 PNG

3.1 基本转换

# 单文件转换
mmdc -i diagram.mmd -o diagram.png

# 指定输出格式（svg / png / pdf）
mmdc -i diagram.mmd -o diagram.svg

# 指定图像宽度（默认 800px）
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080

3.2 常用参数

参数	说明	示例
-i <file>	输入的 .mmd 文件	-i arch.mmd
-o <file>	输出文件路径	-o arch.png
-t <theme>	主题：default / dark / forest / neutral	-t dark
-b <color>	背景色（CSS 颜色或 transparent）	-b transparent
-w <px>	图像宽度（像素）	-w 1200
-H <px>	图像高度（像素）	-H 800
-s <scale>	缩放比例（默认 1）	-s 2
-c <config>	自定义 Mermaid 配置文件（JSON）	-c mermaid.json
--puppeteerConfigFile	Puppeteer 配置文件	--puppeteerConfigFile pp.json

3.3 批量转换（Shell 脚本）

#!/bin/bash
# convert-all-mmd.sh --- 将 docs/ 下所有 .mmd 文件转为 PNG
set -e

INPUT_DIR="docs"
OUTPUT_DIR="docs/images"
THEME="default"

mkdir -p "$OUTPUT_DIR"

for mmd_file in "$INPUT_DIR"/*.mmd; do
    [ -f "$mmd_file" ] || continue
    base=$(basename "$mmd_file" .mmd)
    output="$OUTPUT_DIR/${base}.png"
    echo "Converting: $mmd_file -> $output"
    mmdc -i "$mmd_file" -o "$output" -t "$THEME" -b white
done

echo "Done. Output in $OUTPUT_DIR/"

运行脚本：

chmod +x convert-all-mmd.sh
./convert-all-mmd.sh

3.4 在沙盒/CI 环境中运行（无 GPU）

Puppeteer 需要 --no-sandbox 参数才能在 Docker 或 CI 环境中运行，通过 Puppeteer 配置文件传入：

// puppeteer-config.json
{
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}

mmdc -i diagram.mmd -o diagram.png \
     --puppeteerConfigFile puppeteer-config.json

---

4. Mermaid 图表示例

4.1 流程图（Flowchart）

Drawer::init
BrushBase::notifyGLContextCurrent true
All brushes initialized
Render loop
Drawer::deinit
BrushBase::notifyGLContextCurrent false
Brush destructors --- GL resources released

4.2 序列图（Sequence Diagram）

ImageBrush Drawer Esgui App ImageBrush Drawer Esgui App drawImage(path, area) drawImage(texId, area) bindTexture(texture) setCastArea(area) draw() done 0 0

4.3 类图（Class Diagram）

BrushBase
#mShader
#mCanvasSize
+setCanvasSize(size)
+setRotation(rot)
+setCastArea(area)
+isGLContextCurrent() : bool
#initialize()
ImageBrush
+init(canvasSize)
+bindTexture(texture) : bool
+setFlipY(flip)
+draw() : bool
TextBrush
+init(canvasSize, fontPath)
+drawAsciiText(text, ...)
+drawUnicodeText(text, ...)

---

5. Mermaid 语法速查表

5.1 图表类型总览

图类型	关键字	用途
流程图	graph / flowchart	算法流程、逻辑分支
序列图	sequenceDiagram	组件交互时序
类图	classDiagram	类的继承/组合关系
状态图	stateDiagram-v2	状态机、有限状态自动机
实体关系图	erDiagram	数据库表结构
甘特图	gantt	项目进度、里程碑
饼图	pie	占比分布
Git 图	gitGraph	分支合并历史
思维导图	mindmap	层级概念整理
时间线	timeline	事件时间轴

---

5.2 流程图语法速查

实线带箭头
虚线带箭头
无箭头实线
粗实线
Yes
No
圆角矩形
矩形
菱形判断
圆形
平行四边形

方向关键字 ：TD（上到下）、LR（左到右）、BT（下到上）、RL（右到左）

注释 ：%% 这是注释

子图：

subgraph 子图名称
    A --> B
end

---

5.2b 流程图（Flowchart）完整高级语法

全部节点形状

矩形
圆角矩形
体育场形
子程序
圆柱/数据库
圆形
菱形
六边形
平行四边形 右斜
平行四边形 左斜
梯形
梯形

节点形状速查：

写法	形状	常见用途
[文字]	矩形	处理步骤
(文字)	圆角矩形	一般节点
([文字])	体育场/pill	开始/结束
[[文字]]	双线矩形	子程序调用
[(文字)]	圆柱	数据库/存储
((文字))	圆形	连接点
{文字}	菱形	条件判断
{``{文字}}	六边形	准备/配置
[/文字/]	平行四边形右斜	输入
[\文字\]	平行四边形左斜	输出
[/文字\]	梯形上宽
[\文字/]	梯形下宽

---

全部箭头 / 连线类型

带标签
管道标签
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V

写法	类型	说明
-->	实线箭头	标准流向
--->	加长实线箭头	跨越更多层
-.->	虚线箭头	可选/弱依赖
==>	粗实线箭头	强调流向
--o	圆头	聚合关系
--x	X 头	阻止/禁止
<-->	双向箭头	双向流
o--o	双圆头	双向聚合
x--x	双 X 头	双向禁止
-- "标签" -->	带标签实线	标准写法
`-->	"标签"	`

---

链式连接 + 多目标

Start
A
B
C
End
D
E
F
G
H
I
J
K
L
M
N
O

---

子图（Subgraph）+ 嵌套 + 跨子图连线

退出循环
清理阶段
Brush::destroy()
EglCore::destroy()
渲染循环
vsync
Drawer::begin()
drawText / drawImage
Drawer::end()
swapBuffers()
初始化阶段
EglCore::init()
EglSurface::create()

---

点击事件 + 超链接

Drawer

渲染引擎
TextBrush
ImageBrush

语法：

click 节点ID "URL" "Tooltip" _blank
click 节点ID callback "Tooltip"

---

样式（classDef + style）

App
Drawer
EGL Canvas
GPU

语法	说明
classDef 名称 fill:#hex,stroke:#hex,color:#hex	定义样式类
:::样式名	节点行内应用
class 节点1,节点2 样式名	批量应用
style 节点 属性:值	直接设置单个节点

支持的 CSS 属性：fill / stroke / stroke-width / color / stroke-dasharray / rx / ry

---

图级配置（frontmatter / init 指令）

Studio
Drawer
Canvas

常用主题：default / base / dark / forest / neutral

或在 mmdc 命令行中指定：

mmdc -i input.mmd -o output.svg --theme forest

---

5.2a 序列图（Sequence Diagram）完整语法

OpenGL ES TextBrush Drawer Esgui App OpenGL ES TextBrush Drawer Esgui App loop 每帧（60fps） alt FBO 创建成功 FBO 不完整 opt 首次调用 drawAsciiText par 并发渲染多个元素 critical GL 上下文必须有效 上下文丢失 所有 GL 调用必须在渲染线程 mMutex 保护 atlas 状态 公共 API 层 OpenGL ES 3.0 User 触发 UI 刷新 beginFrame() erase(black) glClear(GL_COLOR_BUFFER_BIT) void drawAsciiText("Hello", area) drawAsciiText(text, area, color) drawAsciiText(text, ...) glTexSubImage2D (atlas update) void glDrawElements (render) void void 0 0 swapBuffers() eglSwapBuffers() EGL_TRUE 0 setRenderTarget(offscreen) (new target active) return (keep old target) call_once initialize() glGenTextures (atlas) textureId drawImage (background) drawFrame (video) drawAsciiText (overlay) GL 调用 LOGW 泄漏警告 glDrawElements rebuildAtlas(atlas, size) ~TextBrush() User

消息类型速查：

符号	线型	箭头	含义
A ->> B	实线	实心	同步调用
A -->> B	虚线	实心	返回值 / 响应
A -x B	实线	×	消息丢失
A --x B	虚线	×	丢失响应
A -) B	实线	开放	异步消息
A --) B	虚线	开放	异步响应

控制块速查：

块类型	语法	用途
激活框	activate X / deactivate X	标记处理期间
循环	loop 说明 ... end	重复执行
条件	alt 说明 ... else ... end	if/else 分支
可选	opt 说明 ... end	可选执行
并行	par ... and ... end	并发执行
异常	critical ... option ... end	try/catch 风格
背景色	rect rgb(r,g,b) ... end	区域高亮
注解	note right of X: 文字	标注说明
自调用	A ->> A: 方法名	递归 / 内部调用
销毁	destroy X	参与者生命周期结束

---

5.3 状态图（State Diagram）

初始化完成
drawPage() 调用
帧渲染完成
setRenderTarget(offscreen)
drawOffscreenComposite()
setRenderTarget(null)
帧完成
GL 错误
FBO 不完整
deinit()
Idle
Drawing
OffscreenMode
Compositing
ScreenMode
Error
FBO 绑定

独立 viewport

关键语法：

• [*] --- 起始/终止伪状态
• A --> B : 事件标签
• state "描述" as 别名
• note right of 状态名 ... end note
• state 并发状态 { ... || ... } --- 并发状态（fork/join）

---

5.4 实体关系图（ER Diagram）

contains
has
stores
STUDIO
LAYOUT_PAGE
string
pageName
PK
int
width
int
height
LAYOUT_ELEMENT
string
eid
PK
string
type
int
zorder
bool
visible
GLYPH_ATLAS
int
textureId
PK
int
atlasSize
bool
isSubpixel
GLYPH_INFO
uint32
codepoint
PK
float
u0
float
v0
float
u1
float
v1

关键语法：

• ||--|| 一对一，||--o{ 一对多，}o--o{ 多对多
• PK 主键，FK 外键，UK 唯一键
• {字段类型 字段名 约束} 定义属性

---

5.5 甘特图（Gantt Chart）

2024-01-07 2024-01-14 2024-01-21 2024-01-28 2024-02-04 分析 BufferPool 分析 ModelRunner 分析 esgui (14 bugs) PERF-1/2/4/5/7 DESIGN-1/2/4/6/7 深度审计 (NEW 系列) 修复 NEW-01~10 v1.0 发布 BUG 修复 PERF 优化 DESIGN 改进 深度审计 里程碑 esgui 优化项目计划

关键语法：

• dateFormat YYYY-MM-DD --- 日期格式
• section 分区名 --- 分组
• :done 已完成，:active 进行中，:crit 关键路径，:milestone 里程碑
• after 任务id --- 依赖关系
• excludes weekends --- 排除周末

---

5.6 Git 图（Git Graph）

main develop feature/esgui init BufferPool fixes ModelRunner fixes esgui 14 BUG fixes PERF-1/2/4/5/7 DESIGN-7/1/2 deep audit fixes v1.0

关键语法：

• commit id: "说明" --- 提交
• branch 分支名 --- 创建分支
• checkout 分支名 --- 切换分支
• merge 分支名 --- 合并
• tag: "标签" --- 打标签

---

5.7 饼图（Pie Chart）

71% 14% 14% esgui 问题类型分布（共35项修复） BUG 修复 PERF 优化 DESIGN 改进

---

5.8 思维导图（Mind Map）

esgui 架构
渲染层 Drawer
ImageBrush
文件图像
FBO 合成
TextBrush
灰度模式
LCD 子像素
FrameBrush
NV12/NV21
YUV420
画布层 Canvas
EGL Context
Offscreen FBO
布局层 Studio
Layout
PageElement
ImageElement
公共类型 Types
PixelFormat
FrameDescriptor
Size2i / Area4i

---

5.9 类图（Class Diagram）完整语法

extends
implements
has
contains
trains
uses
Animal
+String name
#int age
-float weight
+void eat()
#void sleep()
-String breathe() : %% $ = static
+Animal(name) : Animal %% 构造函数

Dog
+String breed
+bark() : void
<<interface>>
Flyable
+fly() : void
<<abstract>>
Bird
+fly() : void
+sing() : void
Wing
+int featherCount
Flock
+String name
Trainer
+String name
+train(Dog) : void
FoodBowl
+GLenum format
Container<T>
+T item
+add(T) : void
+get() : T
<<singleton>>
Singleton
-Singleton instance
+getInstance() : Singleton

关系符号速查：

符号	关系	含义
`<	--`	继承
`<	..`	实现
*--	组合	强拥有，生命周期一致
o--	聚合	弱拥有，独立生命周期
-->	关联	单向关联（有引用）
--	关联	双向关联
..>	依赖	临时使用（参数/局部变量）
..	依赖	双向依赖

类注解关键字 ：<<interface>> / <<abstract>> / <<enum>> / <<singleton>> / <<service>>

---

5.9a 类图------完整补充语法

基数 / 多重性（Cardinality / Multiplicity）

在关系箭头两端可以标注多重性，格式 "基数" 加在箭头符号前后：
owns
renders to
1
1
0..*
0..1
Drawer
+vector<Brush> brushes
Brush
+GLenum type
RenderTarget
+GLuint fbo

常用基数写法："1" "0..1" "1..*" "0..*" "n" "1..n"

---

枚举（Enum）

uses
uses
<<enumeration>>
Direction
NORTH
SOUTH
EAST
WEST
<<enumeration>>
LayoutAlign
LEFT
CENTER
RIGHT
TOP
BOTTOM
Layout
+LayoutAlign align
+Direction direction
+applyAlign() : void

---

命名空间（Namespace）

Mermaid 10.1+ 支持 namespace 块对类进行分组：
canvas
drawer
creates
draws to
manages
1
1..*
EglCore
+EGLDisplay display
+init() : bool
EglSurface
+EGLSurface surface
+swapBuffers() : void
Drawer
+begin() : int
+end() : void
<<interface>>
IBrush
+draw() : void

---

注解（Note）

为类或关系添加文字说明：
calls
TextBrush
-mAtlas GLuint
+drawText(text, x, y) : int
<<external>>
FreeType
+FT_Load_Glyph() : int
负责 LCD 字形渲染\n需在 GL 线程调用 initialize()
外部库，不可在多线程中共用 FT_Library

语法：note for ClassName "文字内容\n支持换行"

---

图方向（Direction）

App
+run() : int
Studio
+loadConfig(path) : bool
Drawer
+begin() : int
Canvas
+swapBuffers() : void

方向选项：direction TB（默认，从上到下）、direction BT、direction LR、direction RL

---

完整方法签名（参数 + 返回值）

Esgui
-mDrawer Drawer
-mCanvas Canvas
-mStudio Studio
+init(width int, height int, title string) : bool
+setRenderTarget(target RenderTarget) : int
+begin() : int
+end() : void
+drawText(text string, x float, y float, size int) : int
+drawImage(path string, x float, y float, w float, h float) : int
+getCurrentFrame(buffer byte_ptr, size int) : int

格式：+methodName(paramName type, ...) ReturnType

类型直接用英文单词（不用 C++ 语法），* 指针写成 type_ptr 或省略。

---

样式 / 高亮（CSS 自定义）

Drawer
+begin() : int
+end() : void
<<interface>>
IBrush
+draw() : void

语法：classDef 样式名 fill:#色值,stroke:#边框色,color:#字体色

应用：class 类名:::样式名 { ... } 或 class ClassName:::styleName（不含成员时）

---

5.10 C4 模型图（架构视图）

Mermaid 支持 C4 Context / Container / Component 三层架构图：
<<person>> 应用程序 使用 esgui 渲染 UI 的宿主程序 <<external_system>> FreeType 2 字形光栅化库 <<external_system>> GPU / OpenGL ES 3 硬件渲染 <<external_system>> Display 物理显示输出 <<system>> Studio 布局管理、页面切换、元素可见性控制 <<system>> Drawer OpenGL ES 3.0 渲染，管理所有 Brush <<system>> Canvas/EGL EGL 上下文创建、surface 管理 esgui Library SYSTEM 调用 loadLayoutConfig / drawPage 调用 drawImage / drawText / drawFrame GL 指令 + EGL swap 字形加载与渲染 OpenGL ES 3.0 指令 帧输出 esgui 系统上下文图

注意：C4 图需安装 @mermaid-js/mermaid-cli ≥ 10.x 才能正确渲染。

---

5.11 时间线图（Timeline）

v0.1 2023-07 项目初始化 基础 EGL 上下文 ImageBrush 原型 v0.2 2023-09 TextBrush 灰度模式 FBO 离屏渲染 FrameBrush NV12 v0.3 --- Bug Fix Round 2024-01 14 个 BUG 修复 PERF-1/2/4/5/7 性能优化 DESIGN-1/2/4/6/7 架构改进 v0.4 --- Deep Audit 2024-02 FBO 上下颠倒修复 LCD 子像素修复 深度审计 NEW-01~10 esgui 开发历史

---

5.12 需求图（Requirement Diagram）

用于描述系统需求及其与设计元素的追溯关系（较新特性，需 Mermaid 9+）：
渲染错误: Mermaid 渲染失败: Parse error on line 4: ...rt { id: REQ-001 text: " ----------------------^ Expecting 'NEWLINE', got 'LINE'

---

5.13 块图（Block Diagram）完整语法

Mermaid 10.3+ 引入的 block-beta 图，适合绘制系统模块分组与数据流：

---

基本块 + columns 布局

应用层

(App)
配置文件

(.json)
Studio

布局管理
esgui 库
Drawer

渲染引擎
Canvas

EGL
GPU

(OpenGL ES 3)

---

节点形状

矩形

(默认)
圆角矩形
圆形
平行四边形

(输入)
平行四边形

(输出)
菱形

(判断)
子程序

形状速查：

写法	形状	用途
["文字"]	矩形	模块/组件
(["文字"])	圆角矩形	流程节点
(("文字"))	圆形	起止点
[/"文字"/]	平行四边形（斜右）	输入
[\"文字"\]	平行四边形（斜左）	输出
{``{"文字"}}	菱形	判断
[["文字"]]	双线矩形	子程序

---

嵌套块 + 样式

应用层
App

main()
StudioAPI

JSON 解析
核心层
Drawer

渲染调度
TextBrush

FreeType 字形
ImageBrush

STB 图片
OffscreenTarget

FBO
硬件抽象层
EglCore

EGL 初始化
EglSurface

交换链

---

箭头类型

模块 A
模块 B
模块 C
模块 D
模块 E
模块 F
%%
实线有箭头（调用）
实线无箭头（关联）
虚线有箭头（可选依赖）
虚线无箭头
标签

---

替代方案：graph TB + subgraph（兼容旧版）

当 Mermaid < 10.3 时，用 graph + subgraph 实现模块图：
硬件抽象
esgui 库
应用层
画刷层
loadConfig
App
Config
Studio

布局管理
Drawer

渲染引擎
TextBrush
ImageBrush
ShapeBrush
EGL Canvas
GPU

subgraph 关键语法：

subgraph ID["显示标题"]
    direction LR    %% 可覆盖子图内部方向
    节点定义...
end

注意：block-beta 需要 Mermaid 10.3+；旧版可用 graph TB + subgraph 代替。
subgraph 内节点可参与外部箭头；block 内节点只通过父块 ID 参与外部连接。

---

6. 参考链接

• Mermaid 官方文档
• Mermaid CLI GitHub
• VSCode Markdown Preview Mermaid Support
• VSCode Mermaid Preview
• Mermaid Live Editor（在线预览）