1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-05 04:18:12 +01:00
mkdocs-material/docs/reference/diagrams.md
2023-02-12 21:05:15 +01:00

287 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
icon: material/graph-outline
---
# 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], a very
popular and flexible solution for drawing diagrams.
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
## Configuration
[:octicons-tag-24: 8.2.0][Diagrams support]
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:
``` yaml
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:
- [x] Works with [instant loading] 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 style sheets]
- [x] Support for both, light and dark color schemes _try it on this page!_
[^1]:
While all [Mermaid.js] features should work out-of-the-box, Material for
MkDocs will currently only adjust the fonts and colors for flowcharts,
sequence diagrams, class diagrams, state diagrams and entity relationship
diagrams. See the section on [other diagrams] for more information why this
is currently not implemented for all diagrams.
[Diagrams support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
[additional style sheets]: ../customization.md#additional-css
[other diagrams]: #other-diagram-types
## 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:
```` markdown title="Flow chart"
``` mermaid
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
```
````
<div class="result" markdown>
``` mermaid
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
```
</div>
[Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
### 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:
```` markdown title="Sequence diagram"
``` 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!
```
````
<div class="result" markdown>
``` 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!
```
</div>
[Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
### 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:
```` markdown title="State diagram"
``` 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 --> [*]
```
````
<div class="result" markdown>
``` 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 --> [*]
```
</div>
[State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram
### Using class diagrams
[Class diagrams] are central to object oriented programing, describing the
structure of a system by modelling entities as classes and relationships between
them:
```` markdown title="Class diagram"
``` 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()
}
```
````
<div class="result" 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()
}
```
</div>
[Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram
### 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:
```` markdown title="Entity-relationship diagram"
``` mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
string name
int pricePerUnit
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```
````
<div class="result" markdown>
``` mermaid
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
LINE-ITEM {
string name
int pricePerUnit
}
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```
</div>
[entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
### Other diagram types
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.
[pie charts]: https://mermaid-js.github.io/mermaid/#/pie
[gantt charts]: https://mermaid-js.github.io/mermaid/#/gantt
[user journeys]: https://mermaid-js.github.io/mermaid/#/user-journey
[git graphs]: https://mermaid-js.github.io/mermaid/#/gitgraph
[requirement diagrams]: https://mermaid-js.github.io/mermaid/#/requirementDiagram