mkdocs-material/docs/reference/diagrams.md

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, a very popular and flexible solution for drawing diagrams.

Configuration

SuperFences

:octicons-file-code-24: Source · :octicons-beaker-24: Experimental · :octicons-heart-fill-24:{ .mdx-heart } Insiders only{ .mdx-insiders }

The SuperFences extension, which is part of Python Markdown Extensions, allows for adding custom fences, which can be used to render Mermaid.js diagrams with zero effort:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid-experimental
          format: !!python/name:pymdownx.superfences.fence_code_format

No further configuration is necessary. Material for MkDocs will automatically load and initialize the Mermaid.js runtime when a page includes a fenced mermaid block. Furthermore:

• Works with instant loading without any additional effort
• Diagrams automatically use fonts and colors defined in mkdocs.yml¹
• Fonts and colors can be customized with additional stylesheets
• Support for both, light and dark color schemes

While it's also possible to integrate Mermaid.js using existing third-party plugins², the new native integration is recommended as it ensures interoperability with all Material for MkDocs features.

Usage

Using diagrams

Mermaid diagrams are written as code blocks with the help of the SuperFences extension. They must be enclosed with two separate lines containing three backticks:

Example:

``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

Result:

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

See the official documentation to learn about all available diagram types.

---

1. While all Mermaid.js features should work out-of-the-box, Material for MkDocs will currently only adjust the fonts and colors for flow charts, class and state diagrams. Support for further diagram types will be added gradually. ↩︎

2. If you don't want to use the native integration, mkdocs-mermaid2-plugin might be a good alternative. However, note that this plugin cannot be used in conjunction with the mkdocs-minify-plugin and doesn't adapt to dark mode. ↩︎