Quarto文档使用Mermaid绘制流程图

Quarto
Mermaid
作者

陈琼

发布日期

2023年10月25日

Quarto文档中支持使用Mermaid绘制流程图，为了绘制流程图，我们可以在Quarto文档中插入Mermaid代码块。

```{mermaid}
%%| label: fig-mermaid
%%| fig-width: 6
%%| fig-cap: |
%%|   How Quarto orchestrates rendering of documents: start with 
%%|   a qmd file, use the Knitr or Jupyter engine to perform the 
%%|   computations and convert it to an md file, then use Pandoc 
%%|   to convert to various file formats including HTML, PDF, 
%%|   and Word.
flowchart LR
  A[qmd] --> B(Knitr)
  A[qmd] --> C(Jupyter)
  B(Knitr) --> D[md]
  C(Jupyter) --> D[md]
  D[md] --> E(pandoc)
  E(pandoc) --> F(HTML)
  E(pandoc) --> G(PDF)
  E(pandoc) --> H(Word)
  E(pandoc) --> I{and more}
```
flowchart LR
  A[qmd] --> B(Knitr)
  A[qmd] --> C(Jupyter)
  B(Knitr) --> D[md]
  C(Jupyter) --> D[md]
  D[md] --> E(pandoc)
  E(pandoc) --> F(HTML)
  E(pandoc) --> G(PDF)
  E(pandoc) --> H(Word)
  E(pandoc) --> I{and more}
图 1: How Quarto orchestrates rendering of documents: start with a qmd file, use the Knitr or Jupyter engine to perform the computations and convert it to an md file, then use Pandoc to convert to various file formats including HTML, PDF, and Word.

基本语法

流程图是由不同的节点和箭头(或线段)组成的图示, 以节点表示不同的步骤, 以箭头表示方向, 从而描述事件或工作的流程。

Mermaid代码定义了节点和箭头是如何创建的，并支持不同类型的箭头、多方向箭头，以及与子图之间的连接。

Mermaid流程图语法以关键字flowchart开头，紧跟着空格和表示流程图方向的关键字，比如LR（左到右）、RL（右到左）、TD（上到下）、BT（下到上），然后另起一行，缩进空格之后添加节点即可。

```{mermaid}
flowchart LR
  A
```
flowchart LR
  A

上面的mermaid代码块只是插入了一个节点，没有表示方向的箭头，也没有另外一个节点。

mermaid里面用 --> 表示方向, 可以指向另外一个节点。

```{mermaid}
flowchart LR
  A --> B
```
flowchart LR
  A --> B

当节点比较多，或者指向比较复杂的时候，我们可以给节点定义ID，只需要在该节点第一次出现的时候定义，后面可以直接利用ID表示指向。

比如： 有个三个节点，A、B、C，A同时指向B和C，那么我们可以给每个节点分配一个id，第二次指示方向的时候，只需使用ID号即可。

```{mermaid}
flowchart LR
  id1(A) --> id2(B)
  id1 --> id3(C)
```
flowchart LR
  id1(A) --> id2(B)
  id1 --> id3(C)

我么可以id号紧跟着各种括号方式定义id，括号内文本代表id的实际内容。

流程图方向

flowchart 空格 方向关键词

方向关键词的选项可以有以下几种：

  • LR 从左至右
  • RL 从右至左
  • TD 从上到下
  • BT 从下到上

节点形状

Mermaid以不同类型的括号组合来表示节点的形状，比如以普通的圆括号对表示圆角长方形等。

下面我们列出mermaid支持的各种节点形状所对应的括号组合。

```{mermaid}
flowchart LR
  id1(id1:圆角长方形)
  id2([id2:椭圆形])

  id3[[id3:卷轴形状]]
  id4[(id4:数据库形状)]
  id1 --> id2 --> id3 --> id4
  id5((id5:圆形))
  id6>id6:标签形状]
  id7{id7:菱形}
  id8{{id8:六角形}}
  id5 --> id6 --> id7 --> id8
  id9[/id9:平行四边形/]
  id10[\id10:平行四边形\]
  id11[/id11:梯形\]
  id12[\id12:倒梯形/]
  id13(((id13:双环圆形)))
  id9 --> id10 --> id11 --> id12 --> id13
```
flowchart LR
  id1(id1:圆角长方形)
  id2([id2:椭圆形])

  id3[[id3:卷轴形状]]
  id4[(id4:数据库形状)]
  id1 --> id2 --> id3 --> id4
  id5((id5:圆形))
  id6>id6:标签形状]
  id7{id7:菱形}
  id8{{id8:六角形}}
  id5 --> id6 --> id7 --> id8
  id9[/id9:平行四边形/]
  id10[\id10:平行四边形\]
  id11[/id11:梯形\]
  id12[\id12:倒梯形/]
  id13(((id13:双环圆形)))
  id9 --> id10 --> id11 --> id12 --> id13

箭头或连接线段

节点之间可以通过箭头或者线段连接起来，mermaid支持指定不同类型的箭头或者线段，或者箭头中间穿插文本。

写法： 带箭头，节点A --> 节点B， 或者不带箭头（线段连接） 节点A — 节点B

也可以在连接线段中间添加文字

写法： 带箭头：节点A -->|线段文本|节点B， 不带箭头：节点A --|线段文本|--节点B

```{mermaid}
flowchart LR
  A --> B
  C --- D
  G -->|线段文本|H
  G1 --线段文本-->H1
  E ---|线段文本|F
  J1 -.-> J2
  J3 -.虚线文本.->J4
  K1 ==> K2
  k3 ==加粗文本==>K4
  L1 ~~~ L2
  A1--text-->B1--text2-->C1
```
flowchart LR
  A --> B
  C --- D
  G -->|线段文本|H
  G1 --线段文本-->H1
  E ---|线段文本|F
  J1 -.-> J2
  J3 -.虚线文本.->J4
  K1 ==> K2
  k3 ==加粗文本==>K4
  L1 ~~~ L2
  A1--text-->B1--text2-->C1

箭头或连接线段的长短

流程图中的每个节点最终都会被分配到呈现图中的一个等级，即一个垂直或水平级别（取决于流程图的方向），这是根据其连接的节点来确定的。默认情况下，连接可以跨越任意数量的等级，但您可以通过在链接定义中添加额外的破折号来要求某个连接比其他链接更长。

在下面的示例中，从节点B到节点E的链接中添加了两个额外的破折号，以使其跨越比常规链接多两个等级：

```{mermaid}
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]
```
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]
长度 1 2 3
正常 --- ---- -----
正常带箭头 --> ---> ---->
加粗 === === ====
加粗带箭头 ==> ===> ====>
虚线 -.- -..- -…-
虚线带箭头 -.-> -..-> -…->

子流程图

Mermaid在绘制流程图时允许我们添一个或多个子流程图。具体方式如下：

subgraph title
  graph definition
end

下面是一个包含三个子图的流程图

```{mermaid}
flowchart TB
    c1-->b1
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    end
```
flowchart TB
    c1-->b1
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    end

子流程图的方向

使用流程图类型的图形，您可以使用direction语句来设置子图呈现的方向，就像在这个示例中一样。

```{mermaid}
flowchart LR
  subgraph TOP
    direction TB
    subgraph B1
        direction RL
        i1 -->f1
    end
    subgraph B2
        direction BT
        i2 -->f2
    end
  end
  A --> TOP --> B
  B1 --> B2
```
flowchart LR
  subgraph TOP
    direction TB
    subgraph B1
        direction RL
        i1 -->f1
    end
    subgraph B2
        direction BT
        i2 -->f2
    end
  end
  A --> TOP --> B
  B1 --> B2

限制性：如果子图的任何节点与外部相连，子图的方向将被忽略。相反，子图将继承父图的方向：

```{mermaid}
flowchart LR
    subgraph subgraph1
        direction TB
        top1[top] --> bottom1[bottom]
    end
    subgraph subgraph2
        direction TB
        top2[top] --> bottom2[bottom]
    end
    %% ^ These subgraphs are identical, except for the links to them:

    %% Link *to* subgraph1: subgraph1 direction is mantained
    outside --> subgraph1
    %% Link *within* subgraph2:
    %% subgraph2 inherits the direction of the top-level graph (LR)
    outside ---> top2
```
flowchart LR
    subgraph subgraph1
        direction TB
        top1[top] --> bottom1[bottom]
    end
    subgraph subgraph2
        direction TB
        top2[top] --> bottom2[bottom]
    end
    %% ^ These subgraphs are identical, except for the links to them:

    %% Link *to* subgraph1: subgraph1 direction is mantained
    outside --> subgraph1
    %% Link *within* subgraph2:
    %% subgraph2 inherits the direction of the top-level graph (LR)
    outside ---> top2

交互

Mermaid允许我们添加一个点击事件到一个节点上，通过点击可以触发JavaScript或者导航到一个外部链接，并在新的浏览器标签中查看结果。

```{mermaid}
flowchart LR
    A-->B
    B-->C
    C-->D
    click B "https://www.github.com" "This is a tooltip for a link"
    click D href "https://www.github.com" "This is a tooltip for a link"
```
flowchart LR
    A-->B
    B-->C
    C-->D
    click B "https://www.github.com" "This is a tooltip for a link"
    click D href "https://www.github.com" "This is a tooltip for a link"

注释

在流程图中可以输入注释，这些注释将被解析器忽略。注释需要单独位于一行，并且必须以 %%（双百分号）开头。从注释开始到下一个换行符之间的任何文本都将被视为注释，包括任何流程语法。

```{mermaid}
flowchart LR
%% 这里都是注释
   A -- text --> B -- text2 --> C
```
flowchart LR
%% 这里都是注释
   A -- text --> B -- text2 --> C