图表¶
¥Diagrams¶
图表有助于沟通不同技术组件之间复杂的关系和互连，是项目文档的重要补充。Material for MkDocs 与Mermaid.js集成，后者是一种非常流行且灵活的图表绘制解决方案。
¥Diagrams help to communicate complex relationships and interconnections between different technical components, and are a great addition to project documentation. Material for MkDocs integrates with Mermaid.js, a very popular and flexible solution for drawing diagrams.
配置¶
¥Configuration¶
8.2.0
此配置启用了对Mermaid.js图表的原生支持。当页面包含mermaid代码块时，Material for MkDocs 将自动初始化 JavaScript 运行时：
¥This configuration enables native support for Mermaid.js diagrams. Material for MkDocs will automatically initialize the JavaScript runtime when a page includes a mermaid code block:
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
无需进一步配置。相比自定义集成的优势：
¥No further configuration is necessary. Advantages over a custom integration:
无需任何额外努力即可立即加载
图表自动使用
mkdocs.yml中定义的字体和颜色1字体和颜色可以通过附加样式表进行自定义
支持明暗配色方案 -在此页面尝试一下！
用法¶
¥Usage¶
使用流程图¶
¥Using flowcharts¶
流程图是表示工作流或流程的图表。这些步骤呈现为各种类型的节点，并通过边连接，描述步骤的必要顺序：
¥Flowcharts are diagrams that represent workflows or processes. The steps are rendered as nodes of various kinds and are connected by edges, describing the necessary order of steps:
``` mermaid
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
```
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];使用序列图¶
¥Using sequence diagrams¶
序列图将特定场景描述为多个对象或参与者之间的顺序交互，包括这些参与者之间交换的消息：
¥Sequence diagrams describe a specific scenario as sequential interactions between multiple objects or actors, including the messages that are exchanged between those actors:
``` mermaid
sequenceDiagram
autonumber
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
sequenceDiagram
autonumber
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!使用状态图¶
¥Using state diagrams¶
状态图是描述系统行为的绝佳工具，它可以将系统分解为有限数量的状态以及这些状态之间的转换：
¥State diagrams are a great tool to describe the behavior of a system, decomposing it into a finite number of states, and transitions between those states:
``` 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 --> [*]使用类图¶
¥Using class diagrams¶
类图是面向对象编程的核心，通过将实体建模为类及其之间的关系来描述系统的结构：
¥Class diagrams are central to object oriented programming, describing the structure of a system by modelling entities as classes and relationships between them:
``` 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()
}使用实体关系图¶
¥Using entity-relationship diagrams¶
实体关系图由实体类型组成，并指定实体之间存在的关系。它描述特定知识领域中相互关联的事物：
¥An entity-relationship diagram is composed of entity types and specifies relationships that exist between entities. It describes inter-related things in a specific domain of knowledge:
``` 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其他图表类型¶
¥Other diagram types¶
除了上面列出的图表类型外， Mermaid.js还支持饼图、甘特图、用户旅程图、 git 图表和需求图，所有这些图表均未得到 Material for MkDocs 的官方支持。这些图表应该仍能像Mermaid.js宣传的那样工作，但我们认为它们不是一个好的选择，主要是因为它们在移动设备上运行不佳。
¥Besides the diagram types listed above, Mermaid.js provides support for pie charts, gantt charts, user journeys, git graphs and requirement diagrams, all of which are not officially supported by Material for MkDocs. Those diagrams should still work as advertised by Mermaid.js, but we don't consider them a good choice, mostly as they don't work well on mobile.
定制¶
¥Customization¶
如果您想要自定义 Mermaid.js，例如引入对ELK 布局的支持，您可以通过向mkdocs.yml添加自定义 JavaScript 文件来实现：
¥If you want to customize Mermaid.js, e.g. to bring in support for ELK layouts, you can do so by adding a custom JavaScript file to your 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",
});
// Important: necessary to make it visible to Material for MkDocs
window.mermaid = mermaid;
虽然所有Mermaid.js功能都应该开箱即用，但 Material for MkDocs 目前仅支持调整流程图、序列图、类图、状态图和实体关系图的字体和颜色。请参阅其他图表部分，了解更多关于为何目前尚未在所有图表中实现此功能的信息。↩