Mkdocs-Mermaid2
A diagrams plugin for Mkdocs

Introduction

Mkdocs-Mermaid2 is a plugin for the MkDocs static sites generator, which allows you to render Mermaid diagrams inserted (as text) into the markdown pages.

• The official repository of Mermaid2 is on github.
• Mermaid2 is available from Pypi.

What is Mermaid?

Mermaid is two things:

1. A simple language for the creation of diagrams.
2. A javascript library (Mermaid.js) for displaying those diagrams in an HTML page.

General Principle

In order to insert a Mermaid diagram in a markdown page,

1. Start a new line with a code fence (triple backticks), with the codeword mermaid.
2. Type the diagram using the Mermaid syntax.
3. End with a code fence.

For example, a markdown page containing the following diagram (left-right graph):

```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.

The mkdocs-mermaid2 plugin takes care of inserting the javascript library into the html page and inserting the script to start it.

Here is another example:

```mermaid
pie title Which animals do you prefer as pets?
    "Dogs" : 386
    "Cats" : 85
    "Rabbits" : 53
    "Hamsters" : 101
```

It will be rendered as (a pie chart):

pie title Which animals do you prefer as pets?
    "Dogs" : 386
    "Cats" : 85
    "Rabbits" : 53
    "Hamsters" : 101

How to write Mermaid diagrams

• For instructions on how to make a diagram, see the official website.
• If you are not familiar, see the Mermaid Overview for Beginners.
• In case of doubt, you will want to test your diagrams in the Mermaid Live Editor.

Installation

Pre-requisites

• Python 3 >= 3.6
• Mkdocs

Automatic

The most up-to-date, stable production version of mkdocs-mermaid2 is available from the pypi repository:

pip install mkdocs-mermaid2-plugin

Manual

The most up-to-date version of the package is available from github.

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

python setup.py install

Installing and running the test examples

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

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.

Specifying your own Mermaid library

By default, mkdocs-mermaid2 automatically inserts the proper calls to Mermaid.js (according to the correct version), so that the diagrams are correctly interpreted.

You may, however, specify your own explicit call:

plugins:
  - search
  - mermaid2:
      javascript: https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs

For more details, see the relative page.

Use of the Material theme

Here are the 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

See the technical explanation.

Other Themes

If you don't use the Material theme, it will be up to you to define the theme and colors of the diagrams, by adding arguments to the plugin, e.g. :

plugins:
    - search
    - mermaid2:
        version: '9.4.3' # only works with version < 10
        arguments:
          theme: 'dark'
          themeVariables:
            primaryColor: '#BB2528'
            primaryTextColor: '#fff'
            primaryBorderColor: '#7C0000'
            lineColor: '#F8B229'
            secondaryColor: '#006100'
            tertiaryColor: '#fff'

Testing

To test your website with a diagram, restart the mkdocs server:

mkdocs serve

In your browser, open the webpage on the localhost (by default: https://localhost:8000)