MarkDown绘制UML图

1. 前言

Markdown是一种轻量级的标记语言，把作者从繁杂的排版工作中解放出来，实现易读易写的文章写作，已经逐渐成为事实上的行业标准。优快云博客支持Markdown可以让广大博友更加专注于博客内容，大赞。但是，不少博友可能对Markdown比较生疏，本博接下来用一个系列文章《Markdown简明教程》扼要介绍Markdown，希望可以对大家有所帮助。

系列教程目录

• 关于Markdown
• Markdown基本使用
• Markdown表格和公式
• Markdown UML图
• 优快云 Markdown快速上手
• Markdown 参考手册

本文为《Markdown简明教程》系列教程的第4篇Markdown UML图，主要讲解Markdown序列图、流程图等, 顺便为介绍了无需任何插件的在线绘制UML的Gravizo。

2. 序列图

2.1 序列图示例

基于js-sequence-diagrams实现了序列图，使用下列的格式声明一个序列图： 
 
在网页上解析结果为：

DHCP客户机DHCP客户机DHCP服务器DHCP服务器IP租约请求IP租约提供IP租约选择IP租约确认

注意：所有的序列图代码需要放在一个语法类型为sequence的代码块中。如下面代码所示。 

2.2 序列图语法

序列图的语法如下图所示。 
 
具体来说：

• 设置title，采用title: message。

title: 序列图标题
 
1

将编译为：

序列图标题

• 设置participant，采用participant: actor

participant A
participant B
 
1
2

将编译为：

AABB

• 设置note， 
  
  • 左侧note： note left of acotor： message
  • 右侧note： note right of actor: message,
  • 覆盖note： note over actor:message

note left of A: 左侧note
note right of B: 右侧note
note over C: 覆盖note
note over A,B: 覆盖多个actor
note over B,C: 测试下\n 换行
 
1
2
3
4
5

将编译为：

AABBCC左侧note右侧note覆盖note覆盖多个actor测试下 换行

• 设置会话， 
  
  • 实线实箭头： actor->actor: message
  • 虚线实箭头： actor–>actor:message
  • 实线虚箭头： actor->>actor:message
  • 虚线虚箭头： actor–>>actor:message

 A->A:自言自语
 A->B:实线实箭头
 A-->B:虚线实箭头
 A->>B:实线虚箭头
 A-->>B:虚线虚箭头
 
1
2
3
4
5

将编译为：

AABB自言自语实线实箭头虚线实箭头实线虚箭头虚线虚箭头

下面的案例演示了序列图语法的混合使用，参见代码： 
 
在网页上解析之后结果为：

作业通知提交序列图教师教师班长班长同学们同学们通知明天作业通知记得明天交作业了解交作业作业

3. 流程图

3.1 流程图示例

优快云 Markdown基于flowchart.js实现流程图。一个简单的流程格式如下代码所示： 
 
编译之后结果为：

StartMy OperationYes or No?Endyesno

注意：所有的流程图代码需要放在一个语法类型为flow的代码块中。如下面代码所示。 

3.2 流程图语法

流程图绘制包括两部分：节点定义和节点连接。

1. 节点定义

格式如下：

节点名称=>节点类型: 提示文本
 
1

• 节点名称可随意起，甚至支持中文。提示文本可以为英文，可以为中文，也可以为空使用默认值。例如：

    st=>start: start
or
    kaishi=>start: 开始
or
    起点=>start: 起点
or
    start=>start
 
1
2
3
4
5
6
7

• 节点类型有start、operation、condition、end等，如下图所示。

start=>start: 开始
login=>operation: 登陆
isLogin=>condition: 是否已登陆？
test=>operation: 进行测试
end=>end: 结束
 
1
2
3
4
5

2. 节点连接

格式如下

一般节点连接：
    节点->节点
条件判断节点连接：
    条件节点(yes)->正确应答节点
    条件节点(no)->错误应答节点
 
1
2
3
4
5

如下面代码所示：

start->isLogin
isLogin(yes)->test
isLogin(no)->login->test
test->end
 
1
2
3
4

编译之后结果为

开始是否已登陆？进行测试结束登陆yesno

接下来做一个复杂的案例，如下图所示，请大家思考如何实现。

开始是否已登录？选择一张图片格式是否正确？完成资料资料是否符合要求？完成登陆yesnoyesnoyesno

列出源代码供大家参考。

start=>start: 开始
isLogin=>condition: 是否已登录？
login=>operation: 登陆
selectPic=>operation: 选择一张图片
isPic=>condition: 格式是否正确？
doIt=>operation: 完成资料
isRight=>condition: 资料是否符合要求？
end=>end: 完成

start->isLogin
isLogin(yes)->selectPic
isLogin(no)->login->selectPic
selectPic->isPic
isPic(yes)->doIt->isRight
isPic(no)->selectPic
isRight(yes)->end
isRight(no)->doIt
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

4. Gravizo

在研究Markdown UML图的时候，找到了不少在线绘制UML图的方式，例如Dot、PlantUML和UMLGraph等方式，并且发现了一个不用使用任何插件就可调用图片的方式-Gravizo。

例如，我们可以使用PlantUML的方式绘制一个用例图，代码如下。 
。

@startuml
left to right direction
skinparam packageStyle rect
actor customer
actor clerk
rectangle checkout {
  customer -- (checkout)
  (checkout) .> (payment) : include
  (help) .> (checkout) : extends
  (checkout) -- clerk
}
@enduml
 
1
2
3
4
5
6
7
8
9
10
11
12

然后，我们就可以使用下面代码调用该图片：

<img src='http://g.gravizo.com/g?
@startuml
left to right direction;
skinparam packageStyle rect;
actor customer;
actor clerk;
rectangle checkout {
  customer -- (checkout);
  (checkout) .> (payment) : include;
  (help) .> (checkout) : extends;
  (checkout) -- clerk;
}
@enduml
'>
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

本文为《Markdown简明教程》系列教程的第4篇Markdown UML图，主要讲解Markdown序列图、流程图等, 顺便为介绍了无需任何插件的在线绘制UML的Gravizo。下一篇文章我们来研读优快云 Markdown的一些特性。

mermaid简介

当撰写文档的时候，对于流程图的生成大多使用Visio等繁重的工具，没有一种轻便的工具能够画图从而简化文档的编写，就像markdown那样。

mermaid解决这个痛点，这是一个类似markdown语法的脚本语言，通过JavaScript实现图表的生成。 
先来看个例子:

1.流程图(flowchart)

graph LR;  
　　A-->B;    
　　A-->C;  
　　B-->D;  
　　C-->D;  
 
1
2
3
4
5
 
1
2
3
4
5

生成的图表如下所示：

 
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!
 
1
2
3
4
5
6
7
8
9
10
11
 
1
2
3
4
5
6
7
8
9
10
11

生成的图表如下所示：

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
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

生成的表如下：

---

下游项目

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
 
1
2
 
1
2

 
这是申明一个由左到右，水平向右的图。\ 
可能方向有： 
- 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];
 
1
2
 
1
2

圆角节点

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

圆节点(The form of a circle)

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

非对称节点(asymetric shape)

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

菱形节点(rhombus)

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

---

连接线

节点间的连接线有多种形状，而且可以在连接线中加入标签：

箭头形连接

graph LR;
  A-->B;
 
1
2
 
1
2

开放行连接

graph LR
A --- B
 
1
2
 
1
2

标签连接

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

箭头标签连接

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

graph LR
 A-- text -->B
 
1
2
 
1
2

虚线(dotted link,点连线)

-.->

graph LR
A-.->B
 
1
2
 
1
2

-.-.

graph LR
A-.-.B
 
1
2
 
1
2

标签虚线

-.text.->

graph LR
A-.text.->B
 
1
2
 
1
2

粗实线

==>

graph LR
A==>B
 
1
2
 
1
2

===

graph LR
A===B
 
1
2
 
1
2

标签粗线

=\=text\==>

graph LR
A==text==>B
 
1
2
 
1
2

=\=text\===

graph LR
A==text===B
 
1
2
 
1
2

---

特殊的语法

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

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

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

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;"]
 
1
2
 
1
2

子图(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
 
1
2
3
4
5
6
7
8
9
10
11
 
1
2
3
4
5
6
7
8
9
10
11

结果：

基础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?);
 
1
2
3
4
5
 
1
2
3
4
5

渲染图如下：

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?);
 
1
2
3
4
5
 
1
2
3
4
5

以上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;
 
1
2
3
4
 
1
2
3
4

渲染结果：

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;
 
1
2
3
4
 
1
2
3
4

备注：这些样式参考CSS样式。

样式类

为了方便样式的使用，可以定义类来使用样式 
类的定义示例：

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

对节点使用样式类：

class nodeId className;
 
1
 
1

同时对多个节点使用相同的样式类：

class nodeId1,nodeId2 className;
 
1
 
1

可以在CSS中提前定义样式类，应用在图表的定义中。

graph LR
      A-->B[AAABBB];
      B-->D;
      class A cssClass;
 
1
2
3
4
 
1
2
3
4

默认样式类：\ 
当没有指定样式的时候，默认采用。

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

示例：

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

结果：

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

序列图(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.
 
1
2
3
4
5
 
1
2
3
4
5

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

 
观察上面的图，如果想让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!
 
1
2
3
4
5
 
1
2
3
4
5

 
消息的语法： 
　　实线或者虚线的使用： 
[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!
 
1
2
3
4
5
6
7
 
1
2
3
4
5
6
7

便签

给序列图增加便签：\ 
具体规则：\ 
[right of | left of | over][Actor]:Text\ 
示例：

sequenceDiagram
　　participant John
　　Note left of John: Text in note
 
1
2
3
 
1
2
3

结果：

跨越两个Actor的便签：

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

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

循环Loops

在序列图中，也可以使用循环，具体规则如下：

loop Loop text
... statements...
end
 
1
2
3
 
1
2
3

示例：

sequenceDiagram
　　Alice->>John: Hello!
　　loop Reply every minute
　　　　John->>Alice:Great!
　　end
 
1
2
3
4
5
 
1
2
3
4
5

渲染结果：

选择ALT

在序列图中选择的表达。规则如下：

alt Describing text
...statements...
else
...statements...
end
 
1
2
3
4
5
 
1
2
3
4
5

或者使用opt(推荐在没有else的情况下使用)

opt Describing text
...statements...
end
 
1
2
3
 
1
2
3

示例：

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
 
1
2
3
4
5
6
7
8
9
10
 
1
2
3
4
5
6
7
8
9
10

渲染结果如下：

---

甘特图(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
 
1
2
3
4
5
6
7
8
9
10
11
 
1
2
3
4
5
6
7
8
9
10
11

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
 
1
2
3
4
5
6
7
8
 
1
2
3
4
5
6
7
8

先来看一个大的例子：

    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
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

获得的图渲染后如下： 

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
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

reference

mermaid docs