mkdocs-mermaid2-plugin

Mkdocs-Mermaid2

An MkDocs plugin that renders Mermaid text descriptions into diagrams (flow charts, sequence diagrams, pie charts, etc.).

• See the mkdocs-mermaid2 documentation on Read The Docs.
• See the package on Pypi.
• View the general Mkdocs documentation

As of version 1.0.0, this plugin works with versions of the Mermaid library > 10, and with lower versions.

• Mkdocs-Mermaid2
  • Introduction
  • Installation
    • Automatic
    • Manual
    • Test
  • Configuration
    • Basic configuration
    • Specifying the version of the Mermaid library
    • Additional settings for the Material theme
  • For more information

Introduction

Mermaid2 allows you to insert mermaid markup in the markdown of your mkdocs pages.

For example, a markdown page containing the following diagram:

```mermaid
graph LR
    hello --> world
    world --> again
    again --> hello
```

will then be displayed in the final HTML page as:

graph LR
    hello --> world
    world --> again
    again --> hello

The diagram will be rendered on the fly by the web browser, with the use of the mermaid javascript library. mkdocs-mermaid2 takes care of inserting the javascript library into the html page.

You can use all the diagrams types supported by the version of the Mermaid javascript library that you are using (flowchart, class, state, timeline, etc.).

Installation

Automatic

pip install mkdocs-mermaid2-plugin

Manual

Clone this repository in a local directory and install the package:

python setup.py install

Test

For running the examples the test directory, you will also need the mkdocs-material theme. You may install it directly, or use the following command to install the whole package:

pip install mkdocs-mermaid2-plugin[test]

Configuration

Basic configuration

To enable this plugin, you need to declare it in your mkdocs config file (mkdocs.yml).

In order to work, the plugin also requires the mermaid javascript library (in the example below, it fetched from the last version from the unpkg repository; change the version no as needed).

plugins:
    - search
    - mermaid2

Note: If you declare plugins, you need to declare all of them, including search (which would otherwise have been installed by default.)

Specifying the version of the Mermaid library

By default, the plugin selects a version of the Mermaid javascript library that is known to work (some versions work better than others).

You may specify a different version of the Mermaid library, like so:

plugins:
  - search
  - mermaid2:
      version: 10.0.2

The plugin will insert the correct call to the javascript library inside the final HTML page.

Additional settings for the Material theme

The Material theme, developed by squidfunk is not mandatory, but recommended.

Mermaid diagrams will automatically adapt their colors to the theme and palette.

Here are the additional recommended settings in the configuration file:

markdown_extensions:
  - pymdownx.superfences:
        # make exceptions to highlighting of code:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid_custom

Do not use these additional settings for other themes, as diagrams will probably not be displayed correctly.

For more information

See the documentation on ReadTheDocs.