--- 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.org/ ## Configuration <!-- md:version 8.2.0 --> 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. [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.org/syntax/flowchart.html ### 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.org/syntax/sequenceDiagram.html ### 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.org/syntax/stateDiagram.html ### 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: ```` 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.org/syntax/classDiagram.html ### 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.org/syntax/entityRelationshipDiagram.html ### 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.org/syntax/pie.html [gantt charts]: https://mermaid.js.org/syntax/gantt.html [user journeys]: https://mermaid.js.org/syntax/userJourney.html [git graphs]: https://mermaid.js.org/syntax/gitgraph.html [requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html