循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例

Markdown 进阶操作

查看更多学习笔记:GitHub:LoveEmiliaForever
Mermaid官网
由于CSDN对某些Mermaid或Markdown语法不支持,因此我的某些效果展示使用图片进行
下面的笔记内容全部是我根据Mermaid官方文档学习的,因为是初学者所以知道哪里不懂,写的比较详细

内嵌 HTML 使用

内嵌 HTML 使用是比较麻烦的事情,不推荐使用
倒不是因为它很难,而是兼容性问题很大,各种不同的 Markdown 支持的 HTML 标签都不一样

这会导致同样一份 markdown 在A网站显示良好,在B网站显示却不尽人意
比如 的 Markdown 是支持的,但 的 Markdown 却不支持这个标签

因此,在要 HTML 内嵌时要确定兼容性问题后再使用

我在此仅给出 GitHub Markdown 支持的常用 HTML 标签

  • 折叠标签

    • 这两个标签合用能产生折叠内容并带有小标题的效果
      <details>
        <summary>小标题summary>
        <p>被折叠的东西p>
      details>
    
  • 定义键盘输入文本

    • 这个标签能产生类似` `的代码片段效果,通常标签之间嵌套使用
  • 定义输出文本、无其它意义文本

    • 通常与嵌套使用
  • 用于定义列表的dldtdd标签

  • 用来定义拼音的标签

  • div标签及其属性itemscopeitemtype

  • 所有的 HTML 实体,即使用&进行转义的字符

Mermaid 绘画使用

Mermaid 简介

Mermaid 是一个类似 Markdown 的开源脚步语言,它能够根据输入的语句自动生成合适的图像,且广泛受支持。
由于 Markdown 支持了 Mermaid 的制作,所以 Markdown 支持内嵌 Mermaid 语法以生成图像。
Mermaid 是通过 JS 实现的插件,全称是mermaid.js,官网是mermaid.js.org 官网

制作了
内嵌到了
衍生了
JS
mermaid.js
Markdown 原生
Markdown 定制

在 Markdown 中使用 Mermaid 需要以下声明语法

  ```mermaid
    具体的 mermaid 语法
  ```

例如上面流程图的源码如下

  ```mermaid
    flowchart LR
      A["JS"]
      B["Mermaid"]
      C["Markdown 原生"]
      D["Markdown 定制"]
      A --制作了--> B --内嵌到了 --> C --衍生了--> D
  ```

Mermaid 中包含了12种可以使用的图表定义结构
分别是:流程图、时序图、类图、状态图、实体关系图、用户行程图、甘特图、饼图、需求图、Git分支可视化、思维导图、ZenUML图

考虑到实用性和学习成本,仅重点学习了9种图形语法
包括:流程图、时序图、类图、状态图、实体关系图、用户行程图、饼图、需求图、思维导图

推荐的学习方法是随用随学 Mermaid 语法并不难学,根据需要进行学习是比较实用的方法

流程图

流程图是由节点和边组成的,在 Mermaid 中有各式各样的语法定义它们的样式、效果等等

流程图-基础语法
声明图像类型

告诉 Mermaid 下列语法是什么图像
可以用flowchartgraph声明流程图类型

声明排列方向

告诉 Mermaid 流程图的排列方向
其中:L代表Left左边R代表Right右边T代表Top上面B代表Bottom下面,顺序为左边的字母到右边的字母

顺序字母 代表意义 顺序字母 代表意义
TB 自上而下 BT 自下而上
RL 从右到左 LR 从左到右
  ```mermaid
      flowchart TB
        subgraph 从左到右
          direction LR
          声明图像类型1 --> 声明排列方向1 --> 声明图像内容1
        end
        subgraph 从右到左
          direction RL
          声明图像类型2 --> 声明排列方向2 --> 声明图像内容2
        end
        subgraph 上下分明
          direction LR
          subgraph 从上到下
            direction TB
            声明图像类型3 --> 声明排列方向3 --> 声明图像内容3
          end
          subgraph 从下到上
            direction BT
            声明图像类型4 --> 声明排列方向4 --> 声明图像内容4
          end
          从上到下 --> 从下到上
        end
        从左到右 --> 从右到左 --> 上下分明
    ```
上下分明
从上到下
声明图像内容3
声明图像类型3
声明排列方向3
从下到上
声明图像内容4
声明图像类型4
声明排列方向4
从右到左
声明图像内容2
声明图像类型2
声明排列方向2
从左到右
声明图像内容1
声明图像类型1
声明排列方向1
声明节点

有两种声明节点的方式

直接声明:直接在连接声明区域声明节点,此时节点名字作为节点内容,节点样式采用默认样式(即[]样式)
完整声明:使用节点名字[节点内容]声明节点,其中的[]代表节点样式,可以改变它以改变节点样式

如采用完整声明则在连接声明区域内以节点名字指代节点

完整声明中的节点内容可以使用Unicode 字符Markdown 语法

  • 使用Unicode 字符时应该将节点内容以" "包裹
  • 使用Markdown 语法时应该将节点内容以"` `"包裹

❗️ 每个节点名字都是唯一的

  ```mermaid
      graph TB
        subgraph 直接声明
          direction LR
          普通节点1 --> 普通节点2 --> 普通节点3
        end
        subgraph 完整声明
          普通节点[这是一个普通节点]
          Unicode节点["Unicode节点"]
          Markdown节点["`**第一行**  
          *第二行*  
          ***第三行***`"]
          普通节点 --> Unicode节点 --> Markdown节点
        end
        直接声明 --> 完整声明
  ```

循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第1张图片

声明节点形状

在介绍完整声明时有提到过可以自定义节点样式,例如使用[ ]包裹节点内容就代表这个节点是默认样式
我们除了默认样式外,Mermaid 还可以定义其它很多的节点样式

节点样式 样式语法 样式效果 节点样式 样式语法 样式效果 节点样式 样式语法 样式效果
默认 [文本] 在这里插入图片描述 圆边 (文本) 在这里插入图片描述 胶囊 ([文本]) 在这里插入图片描述
子程序 [[文本]] 在这里插入图片描述 圆柱 [(文本)] 在这里插入图片描述 圆形 ((文本)) 在这里插入图片描述
六边形 {{文本}} 在这里插入图片描述 棱形 {文本} 循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第2张图片 正四边形 [/文本/] 在这里插入图片描述
反四边形 [\文本\] 在这里插入图片描述 正梯形 [/文本\] 在这里插入图片描述 反梯形 [\文本/] 在这里插入图片描述
旗帜 >文本] 在这里插入图片描述 双圆 (((文本))) 在这里插入图片描述
声明节点间的连接

声明节点间的连接使得有关联的节点能被 Mermaid 识别并绘制连接线
声明单个连接语法A --> B能够声明一条 A 到 B 链接
声明多个连接语法A --> B --> C能够声明A 到 B、B 到 C 共两条链接
多个节点聚合声明语法A & B --> C能够对多个节点进行操作声明 A 到 C、B 到 C 共两条链接

  ```mermaid
      graph LR
        A --单连接声明--> B
        B --多连接声明--> C --多连接声明--> D
        D --多节点聚合--> E & F --多节点聚合--> A
    ```
单连接声明
多连接声明
多连接声明
多节点聚合
多节点聚合
多节点聚合
多节点聚合
A
B
C
D
E
F
调整链接的长度

在某些情况下,可以大致定义链接的长度而改善 Mermaid 画出的图形
Mermaid 内可以定义链接跨越的级数以调整链接长度
想要跨越多少级数,只需要在正常的连接符号上加入对应数量的-.=等符号即可

  ```mermaid
      graph LR
        subgraph 没调整链接长度之前
          direction TB
          %% A --> B 的链接声明是正常的
          A --> B --> D
          D --> E
          E --> B
        end
        subgraph 调整了链接长度之后
          direction TB
          %% A ---> B 的链接声明多了一个 - 符号
          %% 代表着跨1个级别
          A1 ---> B1 --> D1
          D1 --> E1
          E1 --> B1
        end
        没调整链接长度之前 --调整了A到B的跨级为1--> 调整了链接长度之后
  ```

循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第3张图片

调整链接的样式

前面举例所使用的链接样式都是-->代表着有向箭头,Mermaid 内还拥有其它很多链接样式

循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第4张图片

标签
标签
标签
A
B
C
D
E
F
G
H
I
标签
J
K
L
M
N
O
P
注释

让文本以%%开头可以将文本标记为 Mermaid 注释

字符转义

当你要输入特殊字符(与语法相冲突的字符)时,可以使用" "包裹住你的文本,这样就没有关系了
此外 Mermaid 还支持 HTML 的实体(以&表示的字符)

流程图-进阶使用
子流程图

在流程图的里面可以嵌入子流程图,子流程图内仍旧可以嵌入子流程图
将子流程图当成一个整体看待的话,它的行为和普通节点基本一致

子流程图的声明语法如下

  subgraph 子流程图名字[子流程图文本内容(标题)]
    direction 子流程图方向
    子流程图具体信息
  end

子流程图实例

  ```mermaid
    graph TB
    A[HTML 基础]
    subgraph B[HTML 进阶]
      subgraph 属性[各种属性]
        一般属性 --> 特殊属性
      end
      标签 --> 属性 --> 方法
    end
    C[HTML 深入]
    A --> B --> C
  ```

学习 HTML 的过程
循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第5张图片

事件交互

我们可以把页面跳转或是js函数捆绑在节点的点击事件上
这样就能够有一些交互性,这两者的用法和 HTML 差不多

语法如下

  
  click 节点名字 href "网址" "注释" 打开方式
  
  
  
  
  click 节点名字 callback "注释"
  click 节点名字 call callback() "注释"

示例如下

  ```mermaid
    graph LR
      A --> B --> C
      click A callback "引入函数"
      click A call callback() "捆绑函数到节点A的点击事件"
      click B href "https://www.github.com" "前往GitHub" _blank
  ```
A
B
C

由于在他人网页上我们没有定义js脚本的权限,所以点击A节点什么事情都不会发生
但如果你是在浏览器上点击B或C节点,就会跳转到GitHub网页

自定义链接与节点样式
链接样式的定义

由于链接没有像节点一样的节点名字,所以如果要定义单个链接的样式,那么需要使用它的被声明顺序号(从0开始)
例如我声明了三条链接,当我想要为第二条链接添加一个独特的样式时,应该这样做

  linkStyle 1 stroke:#000, stroke-width:0px, color:#000

其中的1就是该链接的被声明顺序号

假如要对全部连接进行改变,去掉顺序号即可

节点样式的定义

由于节点有独一无二的节点名字,当要修改节点样式时,可以根据节点名字定位节点位置
定义节点样式语法如下

  style 节点名字 fill:#000, stroke:#000, stroke-width:0px, color:#000
为节点添加类以定义样式

可以将某些样式和某一类节点绑定在一起,方便管理
Mermaid 中定义类的语法如下

  classDef 类的名字 fill:#000, stroke:#000, stroke-width:0px, color:#000

将节点和类绑定的语法如下

  
  class 节点名字 类的名字
  
  class 节点名字1,节点名字2 类的名字
  
  节点名字:::类的名字
  示例
    A:::MyClass --> B

在可以为节点添加类后,也可以使用CSS根据类选择器为节点添加样式了

使用fontawesome图标

通过使用语法fa:图标名字可以引入fontawesome的图标

时序图

定义参与者

可以在时序图开头声明该时序图的参与者并给它们取别名

  • 以默认样式声明参与者participant 别名 as 展示名
  • 以角色样式声明参与者actor 别名 as 展示名

在声明链接时,使用的是别名
在声明参与者时也可以不设置别名,此时别名展示名一致

  ```mermaid
    sequenceDiagram
      participant 机构A as 大学校园
      actor 学生A as 小明
      机构A ->> 学生A: 发送学业警告书
      学生A ->> 机构A: 回复收到
  ```
大学校园 小明 发送学业警告书 1 回复收到 2 大学校园 小明
参与者分组

可以利用box 颜色 组名 + 声明参与者 + end给参与者分组
其中颜色可以使用rgb(hex,hex,hex)定义,也可以使用英文的颜色单词

  ```mermaid
    sequenceDiagram
      box Yellow 饭店
      participant A as 后厨
      actor B as 服务员
      end
      box rgb(250,50,250) 客人
      actor C as 上司
      actor D as 下属
      end
      D ->> C: 老板要吃什么
      C ->> D: 吃红烧排骨
      D ->> B: 靓仔,一份红烧排骨
      B ->> A: 红烧排骨一份
      A ->> B: 排骨好了
      B ->> D: 菜来了
  ```

循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第6张图片

链接声明

时序图的链接,就是行为传递,语法如下
参与者1 链接样式 参与者2: 传递信息、行为

链接样式共有八种

样式语法 样式描述 样式语法 样式描述
-> 没箭头实线 ->> 有箭头实线
--> 没箭头虚线 -->> 有箭头虚线
-x 末端十字实线 --x 末端十字虚线
-) 末端空心箭头实线 --) 末端空心箭头虚线
  ```mermaid
    sequenceDiagram
      participant A as 小明
      participant B as 小李
      A -> B: 没箭头实线
      A ->> B: 有箭头实线
      A --> B: 没箭头虚线
      A -->> B: 有箭头虚线
      A -x B: 末端十字实线
      A --x B: 末端十字虚线
      A -) B: 末端空心箭头实线
      A --) B: 末端空心箭头虚线
  ```
小明 小李 没箭头实线 1 有箭头实线 2 没箭头虚线 3 有箭头虚线 4 末端十字实线 5 末端十字虚线 6 末端空心箭头实线 7 末端空心箭头虚线 8 小明 小李
参与者激活

激活时间段可以表示参与者正在处理消息或等待回应

Mermaid 中使用activate激活参与者,使用deactivate停止激活参与者
还可以使用简略写法,在链接样式后面添加+代表激活,-代表停止激活
激活状态是可以叠加的

  ```mermaid
    sequenceDiagram
      participant A as 小明
      participant B as 小李
      A ->>+ B: 现在需要一些信息
      A ->> B: 把行程报告写完发我
      activate B
      B -->> A: 行程报告写好了
      deactivate B
      A ->>+ B: 再把报销凭证整理好,发过来
      B -->>- A: OK了,发给你
      B -->>- A: 信息全部发完了
  ```
小明 小李 现在需要一些信息 1 把行程报告写完发我 2 行程报告写好了 3 再把报销凭证整理好,发过来 4 OK了,发给你 5 信息全部发完了 6 小明 小李
添加标签信息

通过语法Note right of或left of或over 参与者: 标签文本可以添加标签
其中 left of right of可以在单个参与者的左边或右边添加标签信息
over可以在多个参与者之间添加标签信息

```mermaid
    sequenceDiagram
      participant A as 小明
      participant B as 小李
      Note left of A: 小明很饿
      A ->> B: 去不去吃饭
      Note over A,B: 小明邀请小李吃饭
      B ->> A: 我还不饿
      Note over A,B: 小李谢绝了
      Note right of B: 小李很饱
  ```
小明 小李 小明很饿 去不去吃饭 1 小明邀请小李吃饭 我还不饿 2 小李谢绝了 小李很饱 小明 小李
循环

通过语法loop 循环名字 + 具体事件 + end为序列图添加循环

  ```mermaid
    sequenceDiagram
      participant A as 小明
      participant B as 小李
      A ->> B: 接下来每分钟给我发一条“你好”
      loop 每过一分钟
        B ->> A: 你好
      end
  ```
小明 小李 接下来每分钟给我发一条“你好” 1 你好 2 loop [每过一分钟] 小明 小李
条件语句

序列图中有两种条件语句,一种是类似if else类型的,另一种是类似switch case类型的
它们的语法如下

  A ->> B: xxxx
  alt 情况描述1
    B ->> A: 描述1对应的xxxx
  else 情况描述2
    B ->> A: 描述2对应的xxxx
  end
  opt 什么什么情况
    B ->> A: 对应的xxxx
  end

示例如下所示

  ```mermaid
    sequenceDiagram
      participant A as 小明
      participant B as 小李
      A ->> B: 小李下班有没有事
      alt 没有事
        B ->> A: 没事,怎么了
        A ->> B: 那去吃饭吧
      else 有事
        B ->> A: 我下班还有其它事要做
        A ->> B: 没事,你先忙
      end
      opt 不确定有没有事
        B ->> A: 我也不确定啊
        A ->> B: 那到时候再说吧
      end
  ```
小明 小李 小李下班有没有事 1 没事,怎么了 2 那去吃饭吧 3 我下班还有其它事要做 4 OK,你先忙 5 alt [没有事] [有事] 我也不确定啊 6 那到时候再说吧 7 opt [不确定有没有事] 小明 小李
平行发生声明

表示声明内发生的事情是同时发生的,这个声明可以嵌套以表述多个事件同时发生
语法如下

  par 情况描述
    A -> B: XXXX
  and 情况描述
    A -> C: XXXX
  end

示例如下所示

  ```mermaid
    sequenceDiagram
      participant A as 小明
      participant B as 小李
      participant C as 小红
      par 大声聊天
        A ->> B: 最近新开的饭店不错
      and 发短信
        A ->> C: 下班要不要一起去新开的饭店
      and
        par 大声聊天
          B ->> A: 对啊,我上次也去吃过了
        and 发短信
          B ->> C: 下班要不要一起去新开的饭店
        end
      end
      par 发短信
        C ->> A: 不用了
        C ->> B: 不用了
      end
  ```
小明 小李 小红 最近新开的饭店不错 1 下班要不要一起去新开的饭店 2 对啊,我上次也去吃过了 3 下班要不要一起去新开的饭店 4 par [大声聊天] [发短信] par [大声聊天] [发短信] 不用了 5 不用了 6 par [发短信] 小明 小李 小红
关键步骤声明

可以在时序图中定义一些必不可少的步骤,也就是必须完成的步骤

语法如下

  sequenceDiagram
  critical 描述xxx
    发生行为
  option 情况xxx
    应对xxx情况的处理行为
  end

示例如下

  ```mermaid
    sequenceDiagram
      participant A as 商店
      actor B as 顾客
      critical 买东西必须要付钱
        A ->> B: 商品
        B ->> A: 钞票
      option 没钱
        A ->> B: 没钱不卖东西
      end
  ```

循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第7张图片

空窗期定义

可以定义空窗期以在某段时间内停止序列的进行,这个空窗期通常用来表示处理一些事件

语法如下

  sequenceDiagram
    break 发生了事件xxx
      空窗期内发生的行为、
    end

示例如下

  ```mermaid
    sequenceDiagram
      participant bank as 银行
      participant database as 数据库
      actor consumer as 顾客
      consumer ->> bank: 我卡里还有多少钱
      bank -->> consumer: 正在查询
      break 查找银行卡的余额
        bank ->> database: 请求数据
        database -->> bank: 返回数据
      end
      bank -->> consumer: 卡里还有xxxx元
  ```

循序渐进-讲解Markdown进阶(Mermaid绘图)-附使用案例_第8张图片

定义背景颜色

可以为一个行为或多个行为定义背景颜色,可使用rgb(hex,hex,hex)定义具体颜色

语法如下

  rect rgb(hex,hex,hex)
  行为
  end

示例如下

  ```mermaid
    sequenceDiagram
      actor driver as 司机
      actor passenger as 乘客
      rect rgb(0, 200, 0)
      driver ->> passenger: 是尾号1234的乘客吗
      rect rgb(50, 150, 200)
      passenger ->> driver: 对
      end
      driver ->> passenger: 上车吧
      end
  ```
司机 乘客 是尾号1234的乘客吗 1 对 2 上车吧 3 司机 乘客
为行为添加序列号

只需要输入autonumber即可

示例

  ```mermaid
    sequenceDiagram
      autonumber
      A ->> B: 身体怎么样
      B ->> B: 自检中
      B ->> A: 身体还不错
      B ->> C: 你的身体怎么样
      C ->> B: 也还可以
  ```
A B C 身体怎么样 1 自检中 2 身体还不错 3 你的身体怎么样 4 也还可以 5 A B C

饼图

饼图能够很好的对比占有部分大小

在 Mermaid 中定义饼图很简单,只需如下语法
showData 是可选的,填上以后数字会被显示在标签以后

  pie showData
    title 图表标题
    "标签1" : 数字1
    "标签2" : 数字2
  ```mermaid
    pie showData
      title 一天都在干什么
      "学习" : 12
      "睡觉" : 9
      "其它" : 3
  ```
50% 38% 13% 一天都在干什么 学习 睡觉 其它

用户行程图

用户行程图能够描述用户在完成特点任务或事情时所采取的步骤,该图可以显示当前用户的工作流程,并揭示未来工作流程可能的改进

要在 Mermaid 定义用户行程图是比较简单的,可以用以下的语法

  journey
    title 图表标题
    section 大阶段计划
      细分任务:评分:参与者1, 参与者2

如下示例

  ```mermaid
    journey
      title 毕业设计安排
      section 选题阶段
        导师申报论文题目 : 7 : 导师
        学生与导师双选 : 7 : 学生, 导师
        导师下达任务书 : 7 : 导师
      section 调研阶段
        学生搜集资料阅读资料 : 4 : 导师, 学生
        学生上交综述与译文 : 5 : 导师, 学生
      section 开题阶段
        完成开题报告与开题答辩 : 7 : 导师, 学生, 专业系, 学院
      section 撰写阶段
        写完三稿论文和设计说明书,经过三位老师评审 : 6 : 导师, 学生
        论文进度期中检查 : 6 : 专业系, 学院
      section 答辩评定阶段
        组织答辩 : 4 : 导师, 答辩小组, 答辩委员会
        成绩评定 : 3 : 导师, 答辩小组, 答辩委员会, 学院
      section 补充
        二次答辩 : 1 : 学院
      section 资料归档
        收尾工作 : 9 : 学院
  ```
专业系 学生 学院 导师 答辩委员会 答辩小组
选题阶段
选题阶段 导师
导师申报论文题目
导师申报论文题目 学生 导师
学生与导师双选
学生与导师双选 导师
导师下达任务书
导师下达任务书
调研阶段
调研阶段 导师 学生
学生搜集资料阅读资料
学生搜集资料阅读资料 导师 学生
学生上交综述与译文
学生上交综述与译文
开题阶段
开题阶段 导师 学生 专业系 学院
完成开题报告与开题答辩
完成开题报告与开题答辩
撰写阶段
撰写阶段 导师 学生
写完三稿论文和设计说明书,经过三位老师评审
写完三稿论文和设计说明书,经过三位老师评审 专业系 学院
论文进度期中检查
论文进度期中检查
答辩评定阶段
答辩评定阶段 导师 答辩小组 答辩委员会
组织答辩
组织答辩 导师 答辩小组 答辩委员会 学院
成绩评定
成绩评定
补充
补充 学院
二次答辩
二次答辩
资料归档
资料归档 学院
收尾工作
收尾工作 毕业设计安排

你可能感兴趣的:(markdown使用,学习,笔记,前端,后端,运维开发,运维)