Native Mermaid.js integration

Experimental support has been released as part of Insiders 1.15.0!

Many users have problems setting up Mermaid for drawing graphs. Material for MkDocs wants to make drawing graphs as simple as adding the relevant graph definition to a Markdown file with everything else automatically being taken care of.

Goals

I’m working on a native Mermaid.js integration as part of Insiders, which will have the following nice properties:

• The theme will automatically set up Mermaid.js as soon as it sees a .mermaid block
• This will work perfectly with instant loading and only load the rather bulky mermaid.js when necessary
• It works with dark mode and is easily customizable through CSS variables
• The colors and fonts will adapt to those chosen by the author in mkdocs.yml
• Omit common problems with Mermaid (i.e. duplicate IDs)
• Consider offline support

While all graph types are supported, not all of them will adapt to the chosen colors and fonts (yet). The progress so far:

• Flow charts
• Class diagrams
• State diagrams
• Sequence diagrams
• Entity-Relationship diagrams
• User Journeys
• Gantt charts
• Pie charts

Usage

Support is currently experimental and can be enabled by adding the following configuration to mkdocs.yml:

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

Material for MkDocs will take care of the rest, only initializing Mermaid.js when necessary. Furthermore, Instant Loading and Mermaid will work perfectly together, so the setup is only necessary once.

Preview

[squidfunk]

I’m currently in the process of migrating Insiders over to v7 and will tackle the Mermaid integration in the next weeks! Sorry for the inconvenience.

[wilhelmer]

The documentation is incorrect. The config snippet includes:

format: !!pymdownx.superfences.fence_code_format

but it should be (as stated above):

format: !!python/name:pymdownx.superfences.fence_code_format

With that change, it runs fine. Looks great, now I have to learn Mermaid 😄