技术图表通常会变得过时,因为编辑它们需要找到原始设计文件、打开单独的应用程序并导出另一个图像。Mermaid 采用不同的方法:图表被定义为文本并存储在文档旁边。
要将 Mermaid 添加到 Markdown,请将图表定义放在围栏代码块内,并使用 mermaid 语言标识符。使用 Mermaid 图表预览 在本地呈现语法、更正错误、复制完整的 Markdown 栅栏或下载 SVG。
本指南从一个小流程图开始,然后构建序列、类、甘特图、思维导图和实体关系图。
Mermaid 30 秒内
基本的 Mermaid 块如下所示:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
开放栅栏告诉兼容的渲染器内容是 Mermaid 语法。 flowchart LR 选择从左到右排列的流程图。其余的线定义节点和连接。
如果目标不支持Mermaid,读者通常会看到代码块而不是图表。该后备保留了源代码,但它并不能替代发布前检查兼容性的方法。
为什么使用基于文本的图表?
Mermaid 当图表满足以下条件时特别有用:
- 属于版本控制文档;
- 随代码或程序一起更改;
- 需要有意义的拉取请求差异;
- 使用标准形状和关系;
- 应该可以在没有专有设计文件的情况下进行编辑;
- 必须在浅色和深色主题中重新生成。
它不太适合详细插图、像素完美布局、徒手注释或需要精确手动放置的视觉设计。在这些情况下,请使用绘图工具并导出可访问的 SVG 或图像。
示例 1:流程图
流程图描述过程、决策或路由规则。
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
关键语法:
TD表示从上到下。LR表示从左到右。[Text]创建一个矩形流程节点。{Text}创建一个决策节点。-->创建定向连接。-->|Label|将文本添加到连接。
使用稳定、短的节点 ID,例如 A or validate。将可见标签保留在括号内,以便更改措辞不需要更改每个连接。
添加子图
子图组相关步骤:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
当分组传达所有权、系统边界或阶段时使用子图。不要仅仅为了装饰而添加盒子。
示例 2:序列图
序列图按时间顺序显示交互。它们非常适合“API”呼叫、身份验证、浏览器工作流程和事件驱动系统。
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
常用箭头:
->>传达了明确的信息。-->>发送虚线响应。participant声明系统或服务。actor声明了人类或外部角色。autonumber按顺序标记交互。
专注于一种场景。试图显示每个替代方案和每个内部函数的序列图变得比代码更难理解。
显示替代路径
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
使用 alt, else,以及 end 用于有意义的分支。如果该分支需要几页解释,请链接到图表下方的散文。
示例 3:类图
类图描述类型、属性、操作、继承和关系。
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
此示例指出 MarkdownDocument 继承自 Document。使用类图作为概念模型,而不是自动替换完整的“API”参考文档。
好的类图会省略那些无助于读者理解设计的细节。显示每个私有字段可以将图表变成源代码的不易搜索的版本。
示例 4:甘特图
甘特图显示随时间变化的任务。它们对于发布计划、迁移和文档项目非常有用。
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
保持日期明确,并在一项任务依赖于另一项任务时使用任务 ID。请记住,当实际项目进度发生变化时,存储在文档中的图表不会自行更新。分配所有权以使其保持最新状态。
示例 5:思维导图
思维导图围绕中心主题组织想法。
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
思维导图在规划或作为高级概述时最有效。它们对于精确关系不太有用,因为树结构可能暗示真实概念重叠的层次结构。
示例 6:实体关系图
ER 图描述数据实体及其关系。
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
使用 ER 图来解释模型,并使用模式或迁移文件来定义实现。图表可能会省略与当前解释无关的索引、约束和字段。
发布前预览Mermaid
直接在长的“Markdown”文档中编写图表会使语法错误难以隔离。集中预览循环速度更快:
- 打开 Mermaid 图表预览.
- 仅粘贴图表定义,不粘贴外部代码栏。
- 渲染图表。
- 读取任何语法错误并更正引用的区域。
- 复制生成的围栏Markdown。
- 当目标需要静态资源时下载 SVG。
- 在真实平台上测试最终的Markdown。
预览以严格的安全配置在浏览器中呈现。即使另一个“Mermaid”安装允许,图表回调和其他交互行为也可能被禁用。这种保守的行为适合通用预览工具。
常见 Mermaid 错误
图表类型丢失
错误:
A --> B
正确:
flowchart LR
A --> B
第一行标识图语法。
标签中的标点符号会破坏解析
引用复杂标签:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
这对于类似于语法的括号、标点符号和标签特别有用。
保留的 Word 被意外使用
Mermaid语法有关键字。官方流程图文档特别警告小写 end 可能会破坏流程图。将其大写或将可见文本放置在带引号的节点标签内:
flowchart LR
Start --> Finish["End"]
代码围栏不正确
语言标识符紧接在左反引号之后:
```mermaid
flowchart LR
A --> B
```
不要缩进整个栅栏,除非周围的 Markdown 语法需要它。
它可以在一个平台上运行,但不能在另一个平台上运行
Mermaid 不断发展,平台可以使用不同的渲染器、版本、安全设置和启用的图表类型。最新“Mermaid”版本支持的语法功能在使用其他实现或旧版本的平台中可能会失败。
对于在平台之间移动的文档,首选广泛支持的语法。在每个所需的目的地测试高级形状、主题、指令和更新的图表类型。
平台兼容性
兼容性应该被测试而不是假设:
| 平台 | 当前记录的方法 | 重要提示 |
|---|---|---|
| GitHub | 使用围栏 mermaid block | GitHub Markdown 文件、问题、讨论、拉取请求和 wiki 中的文档呈现 |
| GitLab | 在 GitLab Flavored Markdown 中使用 Mermaid 代码块 | GitLab 记录了其支持的 Mermaid 版本;自我管理安装可能有所不同 |
| Obsidian | 使用围栏 mermaid 注释中的块 | Obsidian 的渲染器和支持的功能可能会在版本之间发生变化 |
| MkDocs 材料 | 配置Mermaid 自定义围栏 | 本机主题集成需要记录 pymdownx.superfences configuration |
| 通用Markdown解析器 | 通常仅显示代码 | Mermaid 渲染通常需要 JavaScript 集成或构建插件 |
在依赖新功能之前检查当前的官方文档:
对于您控制的文档站点,固定 Mermaid 依赖项版本并测试升级。否则,微小的语法更改可能会改变整个站点的图表。
Mermaid 和辅助功能
渲染的 SVG 不会自动向每个读者传达其含义。将图表视为视觉摘要,并在附近的散文中提供等效的解释。
对于之前的转换流程图,添加文本,例如:
用户选择“DOCX”文件。有效文件在本地转换并显示以供审核;无效文件会产生错误。然后,用户可以复制或下载已审阅的“Markdown”。
无障碍实践:
- 介绍图表解释的内容;
- 在复杂的图表后总结结论;
- 不要仅用颜色来编码含义;
- 使用可读标签而不是内部缩写;
- 在明暗主题中保持足够的对比度;
- 避免需要精确鼠标交互的图表;
- 提供基本信息的文本或表格替代方案;
- 导出 SVG 时请小心。
源代码对作者有用,但对读者来说不一定是一个好的文本替代品。
设计保持可读性的图表
每个图表保留一个目的
图表应该回答诸如“请求失败后会发生什么?”之类的问题。或“哪个服务拥有每个数据存储?”如果它试图解释整个系统,请将其拆分。
喜欢短标签
用散文写出详细的解释。长标签会导致节点变窄、换行笨拙以及移动屏幕上的图表变大。
有意使用方向
从左到右的流程非常适合短流程和请求路径。自上而下的流程通常更适合窄屏幕。在提交之前预览两者。
限制视觉样式
自定义颜色可能与深色模式或平台主题冲突。从渲染器的默认值开始。仅当样式传达含义并在所有必需的主题中保持可读时才添加样式。
将来源放在其解释附近
如果可能,将 Mermaid 块存储在同一个 Markdown 文件中。这使得散文和图表在一篇评论中一起改变。
Mermaid 与静态图像
在以下情况下选择Mermaid:
- 图表经常变化;
- 源代码差异很有价值;
- 布局使用标准图表类型;
- 发布平台可靠地呈现Mermaid。
在以下情况下选择 SVG 或 PNG:
- 设计需要精确的手工布局;
- 目的地不渲染Mermaid;
- 确切的外观必须保持固定;
- 外部共享需要独立资产。
一种有用的混合方式是维护“Mermaid”源并将 SVG 导出到无法渲染它的目标。将源文件放在导出的资源旁边并记录如何重新生成它。
使用 Markdown 转图片 用于共享渲染的 Markdown 内容,或直接从 Mermaid 图表预览 当图表本身就是资产时。
FAQ
Mermaid 是标准 Markdown 的一部分吗?
A 号围栏 mermaid 块是兼容应用程序和构建系统识别的扩展。基本的“Markdown”解析器可以将其呈现为普通代码。
GitHub 是否渲染 Mermaid 图表?
是的。GitHub 的文档描述了 Markdown 文件和多个协作界面中的 Mermaid 渲染。测试较新的语法,因为 GitHub 控制已部署的渲染器和安全设置。
我可以在 Obsidian 中使用 Mermaid 吗?
Obsidian官方帮助文档Mermaid注释中的栅栏式图块。功能支持可能会随着应用程序的渲染器而变化,因此请在安装的版本中验证复杂或新引入的图表类型。
Mermaid 能否取代架构文档?
不。图是系统的一个视图。将其与决策、所有权、约束、故障行为以及权威接口或模式的链接配对。
为什么我的图表在深色模式下呈现不同?
平台可以应用不同的 Mermaid 主题、CSS 变量、字体和背景。在测试完这两个主题之前,请避免硬编码颜色。
我应该提交导出的 SVG 文件吗?
当发布目标需要静态资源或渲染结果必须保持稳定时提交 SVG。还要保留“Mermaid”源和记录的重新生成过程,以防止两个版本发生漂移。
Mermaid 对于机密图表安全吗?
保密性取决于编辑和出版工作流程。WordToMD 的预览会在浏览器中呈现图表,但将 Markdown 或 SVG 发布到存储库或站点则遵循该目标的访问控制。
结论
Mermaid 使图表易于维护,因为源代码与 Markdown 一起存在。从一个小的围栏块开始,选择与问题匹配的图表类型,预览语法,并在最终的渲染器中测试它。当目的地需要静态资产时,使用散文来解释基本含义并导出 SVG。
尝试中的示例 Mermaid 图表预览,编辑周围的文档 Markdown 编辑,并保持图表足够集中,以便未来的贡献者可以理解并更新它,而无需重新绘制整个页面。