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.
What is Mermaid?
Mermaid is two things:
- A simple language for the creation of diagrams.
- 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,
- Start a new line with a code fence (triple backticks),
with the codeword
mermaid
. - Type the diagram using the Mermaid syntax.
- 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.
Note
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.).
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
Caution
If you declare plugins in the config file, 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.
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
Note
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 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'
Tip
As of mkdocs-mermaid2 version 1.0.8, this works also with versions of Mermaid.js >= 10.
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
)