markdown繪圖插件----mermaid簡介

作者：黃永剛

mermaid簡介

當撰寫文檔的時候，對於流程圖的生成大多使用Visio等繁重的工具，沒有一種輕便的工具能夠畫圖從而簡化文檔的編寫，就像markdown那樣。

mermaid解決這個痛點，這是一個類似markdown語法的腳本語言，通過JavaScript實現圖表的生成。
先來看個例子:

1.流程圖(flowchart)

graph LR;  
　　A-->B;    
　　A-->C;  
　　B-->D;  
　　C-->D;  

生成的圖表如下所示：

2. 時序圖(sequence diagram)

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!

生成的圖表如下所示：

3.甘特圖(gantt diagram)

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 json　　　　　　: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

生成的表如下：

---

下游項目

Mermaid 是由Knut Sveidqbist發起旨在輕便化的文檔撰寫。所有開發者:開發者列表

• Gitbook-plugin
• Light table
• Confluence plugin
• Using mermaid via docpad
• Using mermaid in Jekvll
• Using mermaid via Octopress
• Mardown editor Haroopad
• Plugin for atom
• Markdown Plus
• LightPaper 1.2+
• Vim Plugin
  以上的這些都有集成mermaid或者開發相關的插件。

Graph

graph LR
    A --> B

這是申明一個由左到右，水平向右的圖。\
可能方向有：
- TB - top bottom
- BT - bottom top
- RL - right left
- LR - left right
- TD - same as TB

---

節點與形狀

默認節點

graph LR
id1

注意：’id’顯示在節點內部。

文本節點

graph LR
id[This is the text in the box];

圓角節點

graph LR
id(This is the text in the box);

圓節點(The form of a circle)

graph LR
id((This is the text in the circle));

非對稱節點(asymetric shape)

graph LR
id>This is the text in the box]

菱形節點(rhombus)

graph LR
id{This is the text in the box}

---

連接線

節點間的連接線有多種形狀，而且可以在連接線中加入標簽：

箭頭形連接

graph LR;
  A-->B;

開放行連接

graph LR
A --- B

標簽連接

graph LR
A -- This is the label text --- B;

箭頭標簽連接

A–>|text|B\
或者\
A– text –>B

graph LR
 A-- text -->B

虛線(dotted link,點連線)

-.->

graph LR
A-.->B

-.-.

graph LR
A-.-.B

標簽虛線

-.text.->

graph LR
A-.text.->B

粗實線

==>

graph LR A==>B

===

graph LR A===B

標簽粗線

=\=text\==>

graph LR A==text==>B

=\=text\===

graph LR A==text===B

---

特殊的語法

使用引號可以抑制一些特殊的字符的使用，可以避免一些不必要的麻煩。

graph LR\
d1[“This is the (text) in the box”]

graph LR
d1["This is the (text) in the box"]

html字符的轉義字符

轉義字符的使用語法：
流程圖定義如下：

graph LR\
A[“A double quote:#quot;”] –> B[“A dec char:#9829;”]

渲染后的圖如下：

graph LR
        A["A double quote:#quot;"]-->B["A dec char:#9829;"]

子圖(Subgraphs)

subgraph title\
graph definition\
end

示例：

graph TB
        subgraph one
        a1 --> a2
        en
        subgraph two
        b2 --> b2
        end
        subgraph three
        c1 --> c2
        end
        c1 --> a2

結果：

基礎fontawesome支持

如果想加入來自frontawesome的圖表字體,需要像frontawesome網站上那樣引用的那樣。\
詳情請點擊：fontawdsome

引用的語法為：++fa:#icon class name#++

graph TD
      B["fa:fa-twitter for peace"]
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
      B-->E(A fa:fa-camerra-retro perhaps?);

渲染圖如下：

graph TD
      B["fa:fa-twitter for peace"]
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
      B-->E(A fa:fa-camera-retro perhaps?);

以上reference：
1.mermaid docs

---

第二部分—圖表(graph)

---

定義連接線的樣式

graph LR
     id1(Start)-->id2(Stop)
     style id1 fill:#f9f,stroke:#333,stroke-width:4px;
     style id2 fill:#ccf,stroke:#f66,stroke-width:2px,stroke-dasharray:5,5;

渲染結果：

graph LR
     id1(Start)-->id2(Stop)
     style id1 fill:#f9f,stroke:#333,stroke-width:4px;
     style id2 fill:#ccf,stroke:#f66,stroke-width:2px,stroke-dasharray:5,5;

備注：這些樣式參考CSS樣式。

樣式類

為了方便樣式的使用，可以定義類來使用樣式
類的定義示例：

classDef className fill:#f9f,stroke:#333,stroke-width:4px;

對節點使用樣式類：

class nodeId className;

同時對多個節點使用相同的樣式類：

class nodeId1,nodeId2 className;

可以在CSS中提前定義樣式類，應用在圖表的定義中。

graph LR
      A-->B[AAABBB];
      B-->D;
      class A cssClass;

默認樣式類：\
當沒有指定樣式的時候，默認采用。

classDef default fill:#f9f,stroke:#333,stroke-width:4px;

示例：

graph LR
    classDef default fill:#f90,stroke:#555,stroke-width:4px;
    id1(Start)-->id2(Stop)

結果：

graph LR
classDef default fill:#f90,stroke:#555,stroke-width:4px;
id1(Start)-->id2(Stop)

序列圖(sequence diagram)1

序列圖

示例：

sequenceDiagram
　　Alice->>John: Hello John, how are you ?
　　John-->>Alice: Great!
　　Alice--->>John: Huang,you are better .
　　John-->>Alice: yeah, Just not bad.

sequenceDiagram
　　Alice->>John: Hello John, how are you ?
　　John-->>Alice: Great!
　　Alice->>John: Hung,you are better .
　　John-->>Alice: yeah, Just not bad.

觀察上面的圖，如果想讓John出現在前面，如何控制，mermaid通過設定參與者(participants)的順序控制二者的順序。上面的圖可以做如下修改：

sequenceDiagram\
　　participant John\
　　participant Alice\
　　Alice->>John:Hello John,how are you?\
　　John–>>Alice:Great!

sequenceDiagram
　　participant John
　　participant Alice
　　Alice-xJohn:Hello John,how are you?
　　John-->>Alice:Great!

消息的語法：
　　實線或者虛線的使用：
[Actor][Arrow][Actor]:Message text\
Arrow的六種樣式：

• ->
• –>
• ->>
• –>>
• -x
• –x

示例：

sequenceDiagram
    Alice->John: Hello John, how are you ?
    John-->Alice:Great!
    Alice->>John: dont borther me !
    John-->>Alice:Great!
    Alice-xJohn: wait!
    John--xAlice: Ok!

便簽

給序列圖增加便簽：\
具體規則：\
[right of | left of | over][Actor]:Text\
示例：

sequenceDiagram
　　participant John
　　Note left of John: Text in note

結果：

跨越兩個Actor的便簽：

sequenceDiagram
　　Alice->John:Hello John, how are you?
　　Note over Alice,John:A typical interaction

sequenceDiagram
Alice->>John:Hello John, how are you?
Note over Alice,John:A typical interaction

循環Loops

在序列圖中，也可以使用循環，具體規則如下：

loop Loop text
... statements...
end

示例：

sequenceDiagram
　　Alice->>John: Hello!
　　loop Reply every minute
　　　　John->>Alice:Great!
　　end

渲染結果：

選擇ALT

在序列圖中選擇的表達。規則如下：

alt Describing text
...statements...
else
...statements...
end

或者使用opt(推薦在沒有else的情況下使用)

opt Describing text
...statements...
end

示例：

sequenceDiagram
　　Alice->>Bob: Hello Bob, how are you?
　　alt is sick
　　　　Bob->>Alice:not so good :(
　　else is well
　　　　Bob->>Alice:Feeling fresh like a daisy:)
　　end
　　opt Extra response
　　　　Bob->>Alice:Thanks for asking
　　end

渲染結果如下：

---

甘特圖(gantt)2

甘特圖是一類條形圖，由Karol Adamiechi在1896年提出, 而在1910年Henry Gantt也獨立的提出了此種圖形表示。通常用在對項目終端元素和總結元素的開始及完成時間進行的描述。

示例：

gantt
dateFormat YYYY-MM-DD

section S1
T1: 2014-01-01, 9d

section S2
T2: 2014-01-11, 9d

section S3
T3: 2014-01-02, 9d

gantt
dateFormat YYYY-MM-DD
section S1
T1: 2014-01-01, 9d
section S2
T2: 2014-01-11, 9d
section S3
T3: 2014-01-02, 9d

先來看一個大的例子：

    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 section Documentation Describe gantt syntax :active, a1, after des1, 3d Add gantt diagram to demo page :after a1 , 20h Add another diagram to demo page :doc1, after a1 , 48h section Last section Describe gantt syntax :after doc1, 3d Add gantt diagram to demo page : 20h Add another diagram to demo page : 48h

獲得的圖渲染后如下：

header 1	header 2
title	標題
dateFormat	日期格式
section	模塊
Completed	已經完成
Active	當前正在進行
Future	后續待處理
crit	關鍵階段
日期缺失	默認從上一項完成后

關於日期的格式可以參考：
- string-format
- Time-Formatting

Demo

graph TB
    sq[Square shape] --> ci((Circle shape))

    subgraph A subgraph
        di{Diamond with  line break} -.-> ro(Rounded)
        di==>ro2(Rounded square shape)
    end

    e --> od3>Really long text with linebreak<br>in an Odd shape]

    cyr[Cyrillic]-->cyr2((Circle shape Начало));

    classDef green fill:#9f6,stroke:#333,stroke-width:2px;
    classDef orange fill:#f96,stroke:#333,stroke-width:4px;
    class sq,e green
    class di orange

reference

mermaid docs

---

本文原創首發於公眾號：老王和他的IT界朋友們

微信掃描關注微信號：（原創投稿有驚喜！！！）

---

1. 序列圖的樣式的定制需要在可以渲染CSS的地方才可使用，具體可以查閱參考。 ↩
2. 甘特圖的樣式的定制需要在可以渲染CSS的地方才可使用，具體可以查閱參考。 ↩