Troubleshooting

Important notice

If mermaid diagrams are not displayed correctly, or not displayed at all read this section first!

Mermaid diagram is not displayed (or displayed incorrectly)

e.g.

```mermaid
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
```

graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]

Seeing an error message at the place of the diagram?

In recent versions of the javascript library (> 8.6.0), a pretty error message is displayed in case of incorrect syntax:

If you see the error message, it is at least an indication that the mermaid javascript library was called.

The mermaid source code appears as-is (not read)?

In that case, the javascript library was probably not called.

Using superfences, but no diagram is displayed?

If you are using the superfences extension, but you see the source code, you probably forgot to declare the custom_fences, or declared the wrong one. Se more explanations under Declaring the superfences extension

Is mkdocs' version up to date (>= 1.1) ?

To determine the version, use mkdocs -V.

To update mkdocs:

pip install mkdocs --upgrade

Or, if you cloned the repo:

python setup.py install

Is the javascript library properly called?

In order to work, the proper javascript library must called from the html page (by default, the call is inserted automatically).

Control the link used in the HTML page generated, e.g.:

<script type="module">import mermaid from "https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs"</script>

A certain type of diagram (e.g. mindmap, etc.) is not displayed, or the syntax is incorrectly interpreted?

Check the version of the javascript mermaid library you are using (it's indicated in the error message; as a last resort, check in the html page). You can change the library version if needed.

The arguments in the config file (color, etc.) do not work

For example, the following specification (see description) does not work:

plugins:
  - search
  - mermaid2:
      version: '10.1.0'
      arguments:
        theme: 'dark'
        themeVariables:
          primaryColor: '#BB2528'
          primaryTextColor: '#fff'
          primaryBorderColor: '#7C0000'
          lineColor: '#F8B229'
          secondaryColor: '#006100'
          tertiaryColor: '#fff'

Due to the change of javascript library format as of mermaid.js as of version 10.0, this did not work any more (but it worked for lower versions).

This was fixed in version 1.0.8 of the mkdocs-mermaid2 library (see github issue for a full description).

Upgrade mkdocs-mermaid2 to the most recent version.

What if nothing worked?

1. Check the test cases on the github repository and try to run them on your machine; start with the simple website.
2. Open a question on the discussion page for the project.

Explicit calls of the Mermaid library with extra_javascript

Issues with versions

Mermaid.js: Above version 10.0.0, the official format for the Mermaid library is ESM.

MkDocs: Under version 1.5.0, the extra_javascript directive in the config file (mkdocs.yml) does not process ESM libraries correctly.

Version of Mermaid.js < 10

All versions of mkdocs manage correctly the traditional call to javascript code.

<script src="https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js">
</script>

You may specify the mermaid library explicitly in the config file, as long as it is call mermaid (independently of extension):

extra_javascript:
    - https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js

This will be translated in the final HTML page as:

<script src="https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js">

Version of Mermaid.js >= 10

As an ESM javascript library, Mermaid.js requires an import statement.

<script type="module">
import mermaid from "https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs"
</script>

extra_javascript:
    - js/mermaidloader.js

import mermaid from "https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs"

extra_javascript:
    - https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs

extra_javascript:
    - https://cdn.jsdelivr.net/npm/mermaid@10.1.0/dist/mermaid.min.js

Other issues

Rich text diagrams, or links are not displayed properly?

1. As a first step, set the security level to 'loose'.
2. 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).

With pymdownx.details, diagrams in collapsed elements are not displayed?

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:

1. It will create custom HTML tags, <pre class='mermaid'><code>.
2. It will deactivate the auto-load.

You must then use a special custom javascript loader for the diagram, developed by facelessuser:

1. Copy the code from the website of PyMdown Extension.
2. Paste it in a file in your project: docs/js/loader.js
3. Declare this script in the config.yml file:

extra_javascript:
     - js/loader.js

Using the mermaid2.dumps() function

As a bonus, mkdocs-mermaid2 exports the Python 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
}