Mermaid，一个生成结构图的工具

以前在设计软件架构的时候免不了使用 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;

就可以生成以下的流程图

flowchart

序列图

使用以下的序列图定义

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!

就可以生成以下的序列图

sequence

甘特图

使用以下的甘特图定义：

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

就可以生成如下的甘特图。

gantt

如果你还是感觉压力，可以尝试使用在线编辑器去感受下。

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 -

無標題文檔