图表¶
图表有助于传达不同技术组件之间复杂的关系和相互连接，是项目文档的一个很好的补充。Material for MkDocs 集成了 Mermaid.js，这是一个非常流行且灵活的绘图解决方案。
配置¶
此配置启用对 Mermaid.js 图表的原生支持。当页面包含 mermaid 代码块时，Material for MkDocs 将自动初始化 JavaScript 运行时：
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
无需进一步配置。与自定义集成相比的优势：
使用¶
使用流程图¶
流程图 是表示工作流程或过程的图表。步骤以各种类型的节点呈现，并通过边连接，描述步骤的必要顺序：
``` mermaid
graph LR
A[开始] --> B{错误?};
B -->|是| C[嗯...];
C --> D[调试];
D --> B;
B ---->|否| E[太棒了!];
```
graph LR
A[开始] --> B{错误?};
B -->|是| C[嗯...];
C --> D[调试];
D --> B;
B ---->|否| E[太棒了!];使用时序图¶
时序图 描述特定场景中多个对象或参与者之间的顺序交互，包括这些参与者之间交换的消息：
``` mermaid
sequenceDiagram
autonumber
Alice->>John: 你好，约翰，你好吗？
loop 健康检查
John->>John: 对抗疑病症
end
Note right of John: 理性的思考！
John-->>Alice: 很好！
John->>Bob: 你怎么样？
Bob-->>John: 非常好！
```
sequenceDiagram
autonumber
Alice->>John: 你好，约翰，你好吗？
loop 健康检查
John->>John: 对抗疑病症
end
Note right of John: 理性的思考！
John-->>Alice: 很好！
John->>Bob: 你怎么样？
Bob-->>John: 非常好！使用状态图¶
状态图 是描述系统行为的一个很好的工具，将其分解为有限数量的状态和这些状态之间的转换：
``` mermaid
stateDiagram-v2
state fork_state <<fork>>
[*] --> fork_state
fork_state --> State2
fork_state --> State3
state join_state <<join>>
State2 --> join_state
State3 --> join_state
join_state --> State4
State4 --> [*]
```
stateDiagram-v2
state fork_state <<fork>>
[*] --> fork_state
fork_state --> State2
fork_state --> State3
state join_state <<join>>
State2 --> join_state
State3 --> join_state
join_state --> State4
State4 --> [*]使用类图¶
类图 是面向对象编程的核心，通过将实体建模为类及其之间的关系来描述系统的结构：
``` mermaid
classDiagram
Person <|-- Student
Person <|-- Professor
Person : +String name
Person : +String phoneNumber
Person : +String emailAddress
Person: +purchaseParkingPass()
Address "1" <-- "0..1" Person:lives at
class Student{
+int studentNumber
+int averageMark
+isEligibleToEnrol()
+getSeminarsTaken()
}
class Professor{
+int salary
}
class Address{
+String street
+String city
+String state
+int postalCode
+String country
-validate()
+outputAsLabel()
}
```
classDiagram
Person <|-- Student
Person <|-- Professor
Person : +String name
Person : +String phoneNumber
Person : +String emailAddress
Person: +purchaseParkingPass()
Address "1" <-- "0..1" Person:lives at
class Student{
+int studentNumber
+int averageMark
+isEligibleToEnrol()
+getSeminarsTaken()
}
class Professor{
+int salary
}
class Address{
+String street
+String city
+String state
+int postalCode
+String country
-validate()
+outputAsLabel()
}使用实体关系图¶
实体关系图 由实体类型组成，并指定实体之间存在的关系。它描述了特定知识领域中相互关联的事物：
``` mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
string name
int pricePerUnit
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
string name
int pricePerUnit
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses其他图表类型¶
除了上述列出的图表类型，Mermaid.js 还支持 饼图、甘特图、用户旅程、Git 图 和 需求图，这些在 Material for MkDocs 中并未正式支持。这些图表仍应按照 Mermaid.js 的说明正常工作，但我们不认为它们是一个好的选择，主要是因为它们在移动设备上表现不佳。
自定义¶
如果您想自定义 Mermaid.js，例如引入对 ELK 布局 的支持，可以通过将自定义 JavaScript 文件添加到您的 mkdocs.yml 来实现：
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0/dist/mermaid-layout-elk.esm.min.mjs';
mermaid.registerLayoutLoaders(elkLayouts);
mermaid.initialize({
startOnLoad: false,
securityLevel: "loose",
layout: "elk",
});
// 重要：使其对 Material for MkDocs 可见
window.mermaid = mermaid;
-
虽然所有 Mermaid.js 功能应该开箱即用，但 Material for MkDocs 目前仅会调整流程图、时序图、类图、状态图和实体关系图的字体和颜色。有关为什么目前未对所有图表实现此功能的更多信息，请参见 其他图表 部分。 ↩