mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
298 lines
7.2 KiB
Markdown
298 lines
7.2 KiB
Markdown
---
|
|
template: overrides/main.html
|
|
---
|
|
|
|
# Diagrams
|
|
|
|
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][1], a very
|
|
popular and flexible solution for drawing diagrams.
|
|
|
|
[1]: https://mermaid-js.github.io/mermaid/
|
|
|
|
## Configuration
|
|
|
|
### SuperFences
|
|
|
|
[:octicons-file-code-24: Source][2] ·
|
|
:octicons-beaker-24: Experimental ·
|
|
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][2]{ .mdx-insiders }
|
|
|
|
The [SuperFences][3] extension, which is part of [Python Markdown
|
|
Extensions][4], allows for adding __custom fences__, which can be used to
|
|
render [Mermaid.js][1] diagrams with zero effort:
|
|
|
|
``` yaml
|
|
markdown_extensions:
|
|
- pymdownx.superfences:
|
|
custom_fences:
|
|
- name: mermaid
|
|
class: mermaid
|
|
format: !!python/name:pymdownx.superfences.fence_code_format
|
|
```
|
|
|
|
No further configuration is necessary. Material for MkDocs will automatically
|
|
load and initialize the [Mermaid.js][1] runtime when a page includes a [fenced
|
|
`mermaid` block][5]. Furthermore:
|
|
|
|
- [x] Works with [instant loading][6] without any additional effort
|
|
- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
|
|
- [x] Fonts and colors can be customized with [additional stylesheets][7]
|
|
- [x] Support for both, light and dark color schemes
|
|
|
|
_While it's also possible to integrate [Mermaid.js][1] using existing
|
|
third-party plugins[^2], the new native integration is recommended as it
|
|
ensures interoperability with all Material for MkDocs features._
|
|
|
|
[^1]:
|
|
While all [Mermaid.js][1] features should work out-of-the-box, Material for
|
|
MkDocs will currently adjust the fonts and colors for flow charts, sequence
|
|
diagrams, class diagams, state diagrams and entity relationship diagrams.
|
|
|
|
[^2]:
|
|
If you don't want to use the native integration, [mkdocs-mermaid2-plugin][8]
|
|
might be a good alternative. However, note that this plugin cannot be used
|
|
in conjunction with the [mkdocs-minify-plugin][9] and doesn't adapt to
|
|
dark mode.
|
|
|
|
[2]: ../insiders/index.md
|
|
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
|
[4]: https://facelessuser.github.io/pymdown-extensions/
|
|
[5]: #usage
|
|
[6]: ../setup/setting-up-navigation.md#instant-loading
|
|
[7]: ../customization.md#additional-css
|
|
[8]: https://github.com/fralau/mkdocs-mermaid2-plugin
|
|
[9]: https://github.com/byrnereese/mkdocs-minify-plugin
|
|
|
|
## Usage
|
|
|
|
Mermaid diagrams are written as [code blocks][10] with the help of the
|
|
[SuperFences][11] extension. They must be enclosed with two separate lines
|
|
containing three backticks.
|
|
|
|
[10]: code-blocks.md
|
|
[11]: #superfences
|
|
|
|
### Using flowcharts
|
|
|
|
[Flowcharts][12] 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.
|
|
|
|
_Example_:
|
|
|
|
```` markdown
|
|
``` mermaid
|
|
graph LR
|
|
A[Start] --> B{Error?};
|
|
B -->|Yes| C[Hmm...];
|
|
C --> D[Debug];
|
|
D --> B;
|
|
B ---->|No| E[Yay!];
|
|
```
|
|
````
|
|
|
|
_Result_:
|
|
|
|
``` mermaid
|
|
graph LR
|
|
A[Start] --> B{Error?};
|
|
B -->|Yes| C[Hmm...];
|
|
C --> D[Debug];
|
|
D --> B;
|
|
B ---->|No| E[Yay!];
|
|
```
|
|
|
|
[12]: https://mermaid-js.github.io/mermaid/#/flowchart
|
|
|
|
### Using sequence diagrams
|
|
|
|
[Sequence diagrams][13] describe a specific scenario as sequential interactions
|
|
between multiple objects or actors, including the messages that are exchanged
|
|
between those actors.
|
|
|
|
_Example_:
|
|
|
|
```` markdown
|
|
``` mermaid
|
|
sequenceDiagram
|
|
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!
|
|
```
|
|
````
|
|
|
|
_Result_:
|
|
|
|
``` mermaid
|
|
sequenceDiagram
|
|
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!
|
|
```
|
|
|
|
[13]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
|
|
|
|
### Using state diagrams
|
|
|
|
[State diagrams][14] are a great tool to describe the behavior of a system,
|
|
decomposing it into a finite number of states, and transitions between those
|
|
states.
|
|
|
|
_Example_:
|
|
|
|
```` markdown
|
|
``` mermaid
|
|
stateDiagram-v2
|
|
[*] --> Active
|
|
|
|
state Active {
|
|
[*] --> NumLockOff
|
|
NumLockOff --> NumLockOn : EvNumLockPressed
|
|
NumLockOn --> NumLockOff : EvNumLockPressed
|
|
--
|
|
[*] --> CapsLockOff
|
|
CapsLockOff --> CapsLockOn : EvCapsLockPressed
|
|
CapsLockOn --> CapsLockOff : EvCapsLockPressed
|
|
--
|
|
[*] --> ScrollLockOff
|
|
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
|
|
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
|
|
}
|
|
```
|
|
````
|
|
|
|
_Result_:
|
|
|
|
``` mermaid
|
|
stateDiagram-v2
|
|
[*] --> Active
|
|
|
|
state Active {
|
|
[*] --> NumLockOff
|
|
NumLockOff --> NumLockOn : EvNumLockPressed
|
|
NumLockOn --> NumLockOff : EvNumLockPressed
|
|
--
|
|
[*] --> CapsLockOff
|
|
CapsLockOff --> CapsLockOn : EvCapsLockPressed
|
|
CapsLockOn --> CapsLockOff : EvCapsLockPressed
|
|
--
|
|
[*] --> ScrollLockOff
|
|
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
|
|
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
|
|
}
|
|
```
|
|
|
|
[14]: https://mermaid-js.github.io/mermaid/#/stateDiagram
|
|
|
|
### Using class diagrams
|
|
|
|
[Class diagrams][15] are central to object oriented programing, describing the
|
|
structure of a system by modelling entities as classes and relationships between
|
|
them.
|
|
|
|
_Example_:
|
|
|
|
```` markdown
|
|
``` 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()
|
|
}
|
|
```
|
|
````
|
|
|
|
_Result_:
|
|
|
|
``` 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()
|
|
}
|
|
```
|
|
|
|
[15]: https://mermaid-js.github.io/mermaid/#/classDiagram
|
|
|
|
### Using entity-relationship diagrams
|
|
|
|
An [entity-relationship diagram][16] is composed of entity types and specifies
|
|
relationships that exist between entities. It describes inter-related things in
|
|
a specific domain of knowledge.
|
|
|
|
_Example_:
|
|
|
|
```` markdown
|
|
``` mermaid
|
|
erDiagram
|
|
CUSTOMER ||--o{ ORDER : places
|
|
ORDER ||--|{ LINE-ITEM : contains
|
|
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
|
|
```
|
|
````
|
|
|
|
_Result_:
|
|
|
|
``` mermaid
|
|
erDiagram
|
|
CUSTOMER ||--o{ ORDER : places
|
|
ORDER ||--|{ LINE-ITEM : contains
|
|
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
|
|
```
|
|
|
|
[16]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
|