Detailed description of the page production process
Steps for the preparation of an HTML page
There are three steps in the preparation of the HTML page:
flowchart TD
subgraph Page [Page production]
HTML(1. Setting up the HTML tags around the diagram.) --> JS("2. Inserting the call to Mermaid.js")
JS --> Init(3. Initialization/customization)
end
When the webserver serves the statig html page, the Mermaid.js library is executed in the user's browser, to render the diagram.
Conversion to HTML
When converting the markdown into HTML, MkDocs normally inserts the Mermaid code (text) describing the diagram into segments, which will then be processed by the Mermaid.js library (in the user's browser):
<pre class="mermaid">
<code>
...
</code>
</pre>
To make the HTML/css page more robust for most MkDocs themes,
the Mkdocs-Mermaid2 plugin systematically converts
those segments directly into <div>
elements:
<div class="mermaid">
...
</div>
Superfences extension
The principle remains the same when using the Superfences extension.
That extension is not mandatory, except when using the Material theme.
Automatic insertion of the Javascript Library
The plugin then inserts a call to the javascript library.
By default, the plugin will use one of the latest versions of Mermaid.js.
As already mentioned, you can specify, in the config file, the version of Mermaid.js required:
- mermaid2:
version: '10.1.0'
Note
Mkdocs-Macros inserts the Mermaid.js library into the HTML page only when a Mermaid diagram is detected in the markdown page.
Change of distribution format
The behavior of the plugin depends of the version of Mermaid.js.
As of version 10 of the Mermaid javascript library, the plugin uses the ESM format for distribution (see also the changelog).
More information can be found on ECMAScript Module (or ESM), but for our purposes:
- The main file is recognizable because it has the
.mjs
extension. - The HTML call must have the form:
<script src="<URL>", type="module">
- A module in ESM format is not a single file, but a hierarchy of directories/files.
MkDocs-Mermaid2, as of version 1.0, takes this difference into account.
For versions of MkDocs-Mermaid2 >= 1 and versions of Mermaid2.js >= 10
This requires a specific call from the HTML page e.g.:
<script src="https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs" type="module">
</script>
The plugin automatically inserts this call.
For an earlier version of the Mermaid.js (<10), the plugin continues to use the traditional version, which is an all-in-one file.
Those library files are recognizable because they have the .js
extension.
The call in the HTML page is:
<script src="https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js">
mermaid.initialize()
</script>
The plugin automatically inserts this call.
** This is still a valid method.** (Even though the very first versions after 10.0.0 no longer provided this file, later versions have resumed providing it.)
Initialization sequence
Default sequence
To start displaying of the diagrams, the plugin then automatically inserts a separate call to initialize the Mermaid library:
mermaid.initialize()
The user's browser will then read this code and render it on the fly.
No svg/png images are produced during the rendering of that graph.
Additional arguments to the Mermaid engine
Sometimes, however, you may want to add some additional 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:
version: '10.1.0'
arguments:
theme: 'dark'
themeVariables:
primaryColor: '#BB2528'
primaryTextColor: '#fff'
primaryBorderColor: '#7C0000'
lineColor: '#F8B229'
secondaryColor: '#006100'
tertiaryColor: '#fff'
The plugin then automatically adds the initialization sequence:
Both import
and mermaid.initialize()
must be in the same <script>
tag. This is the code produced by the plugin:
<script type="module">import mermaid from "https://unpkg.com/mermaid@10.1.0/dist/mermaid.esm.min.mjs";
mermaid.initialize({
theme: "dark",
themeVariables: {
primaryColor: "#BB2528",
primaryTextColor: "#fff",
primaryBorderColor: "#7C0000",
lineColor: "#F8B229",
secondaryColor: "#006100",
tertiaryColor: "#fff"
}
});
</script>
For traditional (all-in-one file) javascript modules, two calls to the <script>
tag are required. This is the code produced by the plugin:
<script src="https://unpkg.com/mermaid@9.1.0/dist/mermaid.min.js"></script>
<script>mermaid.initialize({
theme: "dark",
themeVariables: {
primaryColor: "#BB2528",
primaryTextColor: "#fff",
primaryBorderColor: "#7C0000",
lineColor: "#F8B229",
secondaryColor: "#006100",
tertiaryColor: "#fff"
}
});
</script>