Tips and Tricks

Advanced Mermaid Functions

Setting the security level to "loose"

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

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.

Use HTML formatting:

```mermaid
graph LR
    hello["<b>Hello</b>"] --> world["<big><i>World</i></big>"]
    world --> mermaid[mermaid web site]
```

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

Adding Hyperlinks to a Diagram

To enable this function, you need to relax mermaid's security level to 'loose'.

```mermaid
graph LR
    hello --> world
    world --> mermaid[mermaid web site]
    click mermaid "https://mermaid-js.github.io/mermaid" "Website"
```

graph LR
    hello --> world
    world --> mermaid[mermaid web site]
    click mermaid "https://mermaid-js.github.io/mermaid" "Website"

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

Using variables and macros in diagrams (MkDocs-Macros)

Variables

What if your diagrams contain a repetitive string, such as the URL of a website in your hyperlinks?

Instead of writing:

graph TD;
    Platform-->Gaming;
    click Gaming "http://127.0.0.1:8000/Gaming/";

You might want to use a variable:

graph TD;
    Platform-->Gaming;
    click Gaming "{{ my_website }}/Gaming/";

You define that variable in your project's config file (mkdocs.yml):

extra:
  my_website: http://127.0.0.1:8000

In this way, you will be able to change that value wherever it appears in the pages, simply by modifying the value in the config file.

To do that, you would have to use the Mkdocs-Macros plugin.

This requires installing the plugin, and declaring it in the config file.

Declare the plugins in the config file, in that order:

plugins:
    - search
    - macros
    - mermaid2

Using macros to generate Mermaid code

If you can program in Python, you could go further than that with MkDocs-Macros: you could use a Python module (main.py) to define macros (functions) that produce hyperlinks or pieces of diagrams from data, or even complete diagrams from a source file.

For example the macro make_choice() would create a full diagram from three components.

def define_env(env):


    @env.macro
    def make_choice(start, choice1, choice2):
        """
        Generate a Mermaid decision diagram with two choices from a starting point,
        within a fenced code block.
        """
        lines = [
            "```mermaid",
            "graph TD",
            f"    {start} -->|first| {choice1}",
            f"    {start} -->|second| {choice2}",
            "```"
        ]
        return "\n".join(lines)

Then you could write, in your markdown page:

{{ make_choice("Start", "OptionA", "OptionB") }}

Which would be translated into:

```mermaid
graph TD
    Start -->|first| OptionA
    Start -->|second| OptionB
```

And then rendered by your browser as:

graph TD
    Start -->|first| OptionA
    Start -->|second| OptionB

Switching between light and dark mode

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();
});