以前在设计软件架构的时候免不了使用 Visio 、OmniGraffle 等这样的工具来生成结构图。
它们普遍有个缺点,「成也 GUI、败也 GUI」。就是无法将自己想法比较直观的直接使用文本来输出,有时候看似鼠标点点拖拖所见即所得,然而思路就在这时候被一闪而过。
说到这里,有可能你会想到使用 Graphviz 等文本图形描述语言来生成结构图。它的确很好用,但是无法直接嵌入到 Web 中。通常做法就是使用 Graphviz 生成图片以后,上传到 Web 然后再插入到页面。
文档和图其实都是内容,我们不应该因为排版的问题耗费太多的时间,精力应该更加专注到内容本身。
说了那么多,这就是我推荐 Mermaid 初衷。
Generation of diagram and flowchart from text in a similar manner as markdown.
多种类型的图表
目前 Mermaid 成熟的结构图模块可以生成 流程图、序列图以及甘特图。它们生成的语法很简单,例如以下的例子:
流程图
使用源代码
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
就可以生成以下的流程图
序列图
使用以下的序列图定义
sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!
就可以生成以下的序列图
甘特图
使用以下的甘特图定义:
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to mermaid :1d
就可以生成如下的甘特图。
如果你还是感觉压力,可以尝试使用在线编辑器去感受下。
Markdown 集成
Mermaid 很方便和 Markdown 集成使用,甚至类似的代码段以后的嵌入即可以使用:
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
Markdown 加载了 Mermaid 插件以后,解析器会自动将代码块中的代码渲染为 SVG 格式的结构图。
gitbook 集成
如果您习惯使用 gitbook 编写技术文档,那么 Mermaid 会让你事半功倍。只需要在 package.json
中加入对应的 devDependencies
就可以直接使用。
"devDependencies": {
"gitbook-cli": "^2.3.2",
"mermaid": "^8.0.0-rc.6",
"..."
}
使用 CSS 自定义样式
Mermaid 使用 JavaScript 编写并使用 SVG 输出,因此天生自带了 Web 相关的属性。可以很方便的使用 CSS 定义对应的样式类(Style CSS)来自定义样式。
架构简单便于扩展
Mermaid 只是个结构图的生成引擎,如果你想让它生成其他的结构图,那么可以花点时间来扩展它。简单的说,扩展 Mermaid 生成结构图只需要两个因素:语法定义、以及图形绘制逻辑。
在这里有个比较简单的介绍如何扩展 Mermaid,当然你也可以参考现成的结构图源代码来对比输出。
新项目
Mermaid 是个比较新的工具,功能和文档都在不断的完善中。我发起了个 Mermaid 中文文档翻译计划,目前基本的文档都已经翻译完成,可以在这里阅读。
如果您有任何的意见或者建议,也欢迎您不吝提出。
- eof -
Mermaid 新么?恰恰相反,我觉得它已经过了活跃期了。https://github.com/knsv/mermaid/graphs/code-frequency 在 17 年 10 月之后,基本处于不开发状态,Issue List 大量没人回复。我现在已经弃用 Mermaid,换成丑丑可靠的 plantuml + graphviz了。
我觉得作为工具其实满足需求就行,主要还是考虑能不能提高生产力