An MkDocs plugin that renders textual graph descriptions into Mermaid graphs (flow charts, sequence diagrams, pie charts, etc.).
This is a fork from Pugong Liu's excellent project, which is no longer maintained. It offers expanded documentation as well as new functions.
- How it works
- Installation
- Configuration
- Usage
- Tips and Tricks
- Compatibility
- Troubleshooting: the mermaid diagram is not being displayed
- Seeing an error message at the place of the diagram?
- The mermaid source code appears as-is (not read)?
- Using another theme than material ?
- Using superfences, but no diagram is displayed?
- Is mkdocs' version up to date (>= 1.1) ?
- Is the javascript library properly called?
- Rich text diagrams, or links are not displayed properly?
- With pymdownx.details, diagrams in collapsed elements are not displayed?
- Using the mermaid2.dumps() function
If you do not wish to learn the details under the hood, skip to the Installation section.
Normally mkdocs inserts the Mermaid code (text) describing the diagram
into segments <pre><code class='mermaid>
:
<pre><div class="mermaid">
...
<\pre><\div>
To make the HTML/css page more robust, the mermaid plugin converts
those segments into <div>
elements in the final HTML page:
<div class="mermaid">
...
<\div>
It also inserts a call to the javascript library :
<script>
mermaid.initialize(...)
</script>
To interpret that code it inserts a call to the Mermaid library:
<script src="https://unpkg.com/mermaid/dist/mermaid.min.js">
</script>
The user's browser will then read this code and render it on the fly.
No svg/png images are harmed during the rendering of that graph.
pip install mkdocs-mermaid2-plugin
Clone this repository in a local directory and install the package:
python setup.py install
To enable this plugin, you need to declare it in your config file
(mkdocs.yml
).
In order to work, the plugin also requires the mermaid javascript library (in the exemple 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.)
Important: If you use another theme than material you must use a version of the plugin >= 0.5.0.
For plugin version >= 0.4
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: 8.6.4
If you use a version of the plugin >= 0.4, the basic steps are sufficient.
You may specify the mermaid library explicitly, as long as it is call mermaid (independently of extension):
extra_javascript:
- https://unpkg.com/[email protected]/dist/mermaid.min.js
For the latest version:
extra_javascript:
- https://unpkg.com/mermaid/dist/mermaid.min.js
Note for plugin version < 0.4: You must* include the mermaid.min.js (local or remotely) in your
mkdocs.yml
. If you want to be on the safe side, you may want to specify a version that you know is working for you, e.g.https://unpkg.com/[email protected]/dist/mermaid.min.js
In order to insert a Mermaid diagram in a markdown page, simply type it using the mermaid syntax, and surround it with the code fence for Mermaid:
```mermaid
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
```
- For instructions on how to make a diagram, see the official website.
- If you are not familiar, see the n00bs' introduction to mermaid.
- In case of doubt, you will want to test your diagrams in the Mermaid Live Editor.
By default, the plugin automatically inserts
the a Javascript command mermaid.initialize();
in the HTML pages, which starts the interpretation.
Sometimes, however, you may want to add some
initialization commands (see full list).
For example, you could change the theme of the diagram, using 'dark' instead of the default one. Simply add those arguments in the config file, e.g.
plugins:
- search
- mermaid2:
arguments:
theme: 'dark'
extra_javascript:
- https://unpkg.com/mermaid/dist/mermaid.min.js
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
)
New in 0.3.0
To make modifications that are not possible with css, it can be useful to insert a callback function (Javascript) into the target HTML page.
This can be done using the standard pattern, e.g.:
<script src="js/extra.js">
<script>mermaid.initialize({
theme: "dark",
mermaid: {
callback: myMermaidCallbackFunction
}
});</script>
In this case, myMermaidCallbackFunction
is located in
the js/extra.js
on the site's root directory.
Here is a simplistic example:
// js/extra.js
function myMermaidCallbackFunction(id) {
console.log('myMermaidCallbackFunction', id);
You will see the results if you display the browser's console.
This can be translated into the config (mkdocs.yaml
) file as:
plugins:
- mermaid2:
arguments:
theme: dark
mermaid:
callback: ^myMermaidCallbackFunction
extra_javascript:
- https://unpkg.com/mermaid/dist/mermaid.min.js
- js/extra.js
- Note that the name of the function must be preceded by a ^ (caret) to signify it's a literal and not a string.
- Consider the directory path for the script
as relative to the document directory (
docs
). Mkdocs will then put it in the proper place in the hierarchy of the html pages.
To access these functions, you need to relax mermaid's security level, (since version 8.2).
This requires, of course, your application taking responsibility for the security of the diagram source.
If that is OK with you, you can set the argument in the configuration of the plugin:
- mermaid2:
arguments:
securityLevel: 'loose'
To enable this function, you need to relax mermaid's security level to 'loose'.
You may use HTML in the diagram.
Note: This is guaranteed to work with Mermaid 8.6.4, but does not work e.g. on 8.7.0.
graph LR
hello["<b>Hello</b>"] --> world["<big><i>World</i></big>"]
world --> mermaid[mermaid web site]
Use this in the config file:
extra_javascript:
- https://unpkg.com/[email protected]/dist/mermaid.min.js
To enable this function, you need to relax mermaid's security level to 'loose'.
Use the click directive in the language (for more information, see Interaction on the official mermaid website).
graph LR
hello --> world
world --> mermaid[mermaid web site]
click mermaid "https://mermaid-js.github.io/mermaid" "Website"
To enable this function, you need to relax mermaid's security level to 'loose'.
It is possible to add hyperlinks to a diagram, e.g.:
box1[An <b>important</b> <a href="http://google.com">link</a>]
Using a combination of the literal (^
) functionality of this plugin and the
prefers-color-scheme
CSS media feature, one can have the plugin automatically enable dark mode.
plugins:
- search
- mermaid2:
arguments:
theme: |
^(window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'
This works well with the scheme: preference
option in
mkdocs-material and referenced in their documentation.
Here is a short list of comptabilities and incompatibilities for the mermaid plugin:
Item | Type | Status | Note |
---|---|---|---|
mkdocs | theme | YES | (default) plugin version >= 0.5 |
material | theme | YES | |
windmill | theme | YES | plugin version >= 0.5 |
admonition | extension | YES | |
footnotes | extension | YES | |
minify | plugin | NO | Breaks the mermaid diagrams. |
pymdownx.highlight | extension | NO | Use pymdownx.superfences |
pymdownx.superfences | extension | OK | see paragraph |
search | plugin | OK | Do not forget to declare it in config.yml . |
It is quite natural that we want to display mermaid diagrams, while having usual code highlighting (for bash, python, etc.).
Symptom: The mermaid code is not transformed into a diagram, but processed as code to be displayed (colors, etc.).
The likely reason is that you have a markdown extension that interprets all fenced code as code to display, and it prevents the mkdocs-mermaid2 plugin from doing its job.
Do not use the codehilite markdown extension.
Instead, use facelessusers's splendid PyMdown's superfences; and use the custom fences facility.
In the config file (mkdocs.yaml
):
markdown_extensions:
- pymdownx.superfences:
# make exceptions to highlighting of code:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid
It means:
- Take the fenced parts marked with mermaid
- Turn them into
class='mermaid'
. - To format those pieces, use the function
fence_mermaid
, from the mermaid2 package.
IMPORTANT: Note that the superfences will be slightly more demanding with HTML tags inside a mermaid diagram: take care to always close the HTML tags that require it (e.g.
<small>
must have its corresponding</small>
tag). Otherwise, the extension system will attempt to close those tags and it will break the diagram.
To start with, use a simple diagram that you know is syntactically correct.
e.g.
```mermaid
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
```
In recent versions of the javascript library (> 8.6.0), a pretty error message is displayed in case of incorrect syntax:
In earlier versions, the library displays nothing, which can be confusing.
If you see the error message, it is at least an indication that the mermaid javascript library was called.
In that case, the javascript library was probably not called. See the next questions.
If the diagram is not rendered, upgrade to plugin version >= 0.5.0
If you are using the superfences extension, but you see the source code, you probably forgot to declare the custom_fences. Se more explanations under Declaring the superfences extension
Use mkdocs -v
.
If not, update it:
pip install mkdocs --upgrade
Or, if you cloned this repo:
python setup.py install
Note that that this is no longer mandatory since version 0.4 of the plugin. You may want to try to remove this call, in case there was an error.
In order to work, the proper javascript library must called from the html page.
The configuration file (mkdocs.yml
) should contain the following line:
extra_javascript:
- https://unpkg.com/mermaid/dist/mermaid.min.js
Every diagram should start with a valid preamble, e.g. graph TD
.
In case of doubt, you may want to test your diagram in the Mermaid Live Editor.
Note, however, that the Mermaid Live Editor does not support loose mode (with HTML code in the mermaid code).
- As a first step, set the security level to 'loose'.
- Make sure you use a compatible version of the javascript library
(8.6.4, 8.8.0,
8.7.0). In principle, the version used by the plugin is compatible (see instructions to change the version).
This fix is experimental (it has been tested once and it worked).
If you declared pymdownx.details
in config.yml
(under markdown_extensions
), you may notice that a diagram will not
display correctly in that case:
???- note "Collapsed"
```mermaid
graph TD
A[Client] --> B[Load Balancer]
```
This is additional text.
Depending on the browser, you may have a dot, or nothing, etc.
In that case, use the following declaration in your markdown_extensions
:
- pymdownx.superfences:
# make exceptions to highlighting of code:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom
The use of this function will trigger a custom behavior, with two effects:
- It will create custom HTML tags,
<pre class='mermaid'><code>
. - It will deactivate the auto-load.
You must then use a special custom javascript loader for the diagram, developed by facelessuser:
- Copy the code from the website of PyMdown Extension.
- Paste it in a file in your project:
docs/js/loader.js
- Declare this script in the
config.yml
file:
extra_javascript:
- js/loader.js
As a bonus, mermaid2 exports the function dumps()
which produces a string
describing a JavaScript object.
It can be used to help generate JavaScript code from Python
(this is typically needed, when generating an HTML page that contains
JavaScript).
A JavaScript object is not exactly the same as a JSON object. The reason why this why introduced is that sometimes one needs to produce a key/value pair as:
foo = MyFunctioName
where the value is not a string but an identifier (in this case: a function name).
Here is an example:
import mermaid2
obj = { "hello": "world",
"barbaz": "^bazbar",
"foo": {"bar": 2},
"bar": True}
s = mermaid2.dumps(obj)
The purpose of the caret is to specify that the value should be an identifier and not a string. The result will be:
{
hello: "world",
barbaz: bazbar,
foo: {
bar: 2
},
bar: true
}