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¶

Source · Experimental · Insiders only

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:

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