Skip to content

Tips and Tricks

Setting the security level to "loose"

To access the following functions, you need to relax mermaid's security level, (since version 8.2).

Caution

This requires you, of course, to take the 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'

Formatting text in diagrams

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["Hello"] --> world["World"]
    world --> mermaid[mermaid web site]

Use this in the config file: 

extra_javascript:
     - https://unpkg.com/mermaid@8.6.4/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"

It is possible to add hyperlinks to a diagram, e.g.:

box1[An <b>important</b> <a href="https://google.com">link</a>]

Auto-configure dark mode based on Host OS

Using a combination of the unquote (^) 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.

Material Theme: Switching on the fly between light and dark mode

The Material theme for MkDocs allows toggling between colors. Unfortunately the Mermaid diagram will not switch out of the box from light to dark or vice versa.

This solution is similar to switch the theme according to the OS color, though that earlier, simpler solution cannot toggle dynamically.

A workable solution has been proposed by elgalu (for more information see Issue 39).

mkdocs.yml

(The palette is an example, where primary color, accent, icons, toggle message, etc. can be adapted to your needs.)

theme:
  name: material
  # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: light-blue
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: deep orange
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

  # https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
  pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid

plugins:
  - mermaid2:
      arguments:
        # test if its __palette_1 (dark) or __palette_2 (light)
        # for mkdocs-material >=8.0.0
        theme: |
          ^(JSON.parse(__md_get("__palette").index == 1)) ? 'dark' : 'light'
#       for mkdocs-material <8.0.0
#         ^(JSON.parse(window.localStorage.getItem(__prefix('__palette'))).index == 1) ? 'dark' : 'light'

extra_javascript:
    - extra/refresh_on_toggle_dark_light.js

The caret operator (^) means "unquote". It is used here to insert Javascript code into the initialization code of mermaid.initialize().

docs/extra/refresh_on_toggle_dark_light.js

To avoid refreshing the page after switching between dark/light modes so that Mermaid diagram can be updated, two listeners must be installed, which are instructed to reload the page, whenever they detect a change.

That is the function of the additional script (refresh_on_toggle_dark_light.js):

var paletteSwitcher1 = document.getElementById("__palette_1");
var paletteSwitcher2 = document.getElementById("__palette_2");

paletteSwitcher1.addEventListener("change", function () {
  location.reload();
});

paletteSwitcher2.addEventListener("change", function () {
  location.reload();
});