Mermaid rendering issues on mkdocs build

[dominik4545]

Dear community,

I have built such an amazing site using markdown and mkdocs-material. Within my page, mermaid diagrams are heavily used.
During the whole testing phase, everything worked perfectly fine when running mkdocs serve, so I wanted to ship the page using mkdocs build.
Unfortunately, mermaid raises an Syntax error but the diagram looks perfectly fine when when running mkdocs serve.

Do you have any idea why this happens?

What I did so far:

• Created a new mkdocs project containing just a single file with the diagram --> error still exists
• Checked the configuration based on the diagrams section of Material for MkDocs
• Installed the mkdocs-mermaid2-plugin and went through their troubleshooting

I really appreciate any idea to understand what happens here and to get rid of this error.

My Environment:
Ubuntu 22.04.4 LTS
Python 3.10.12

Installed packages (in my venv based on my requirements.txt

Requirement already satisfied: Jinja2 in ./venv/lib/python3.10/site-packages (from -r requirements.txt (line 1)) (3.1.3)
Requirement already satisfied: markdown_grid_tables in ./venv/lib/python3.10/site-packages (from -r requirements.txt (line 2)) (0.3.1)
Requirement already satisfied: mkdocs-autorefs in ./venv/lib/python3.10/site-packages (from -r requirements.txt (line 3)) (1.0.1)
Requirement already satisfied: mkdocs-awesome-pages-plugin in ./venv/lib/python3.10/site-packages (from -r requirements.txt (line 4)) (2.9.2)
Requirement already satisfied: mkdocs-material in ./venv/lib/python3.10/site-packages (from -r requirements.txt (line 5)) (9.5.19)
Requirement already satisfied: mkdocs-mermaid2-plugin in ./venv/lib/python3.10/site-packages (from -r requirements.txt (line 6)) (1.1.1)
Requirement already satisfied: MarkupSafe>=2.0 in ./venv/lib/python3.10/site-packages (from Jinja2->-r requirements.txt (line 1)) (2.1.5)
Requirement already satisfied: markdown>=3.0.0 in ./venv/lib/python3.10/site-packages (from markdown_grid_tables->-r requirements.txt (line 2)) (3.6)
Requirement already satisfied: mkdocs>=1.1 in ./venv/lib/python3.10/site-packages (from mkdocs-autorefs->-r requirements.txt (line 3)) (1.6.0)
Requirement already satisfied: wcmatch>=7 in ./venv/lib/python3.10/site-packages (from mkdocs-awesome-pages-plugin->-r requirements.txt (line 4)) (8.5.1)
Requirement already satisfied: natsort>=8.1.0 in ./venv/lib/python3.10/site-packages (from mkdocs-awesome-pages-plugin->-r requirements.txt (line 4)) (8.4.0)
Requirement already satisfied: regex>=2022.4 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (2024.4.16)
Requirement already satisfied: requests~=2.26 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (2.31.0)
Requirement already satisfied: pymdown-extensions~=10.2 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (10.8)
Requirement already satisfied: paginate~=0.5 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (0.5.6)
Requirement already satisfied: mkdocs-material-extensions~=1.3 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (1.3.1)
Requirement already satisfied: pygments~=2.16 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (2.17.2)
Requirement already satisfied: babel~=2.10 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (2.14.0)
Requirement already satisfied: colorama~=0.4 in ./venv/lib/python3.10/site-packages (from mkdocs-material->-r requirements.txt (line 5)) (0.4.6)
Requirement already satisfied: jsbeautifier in ./venv/lib/python3.10/site-packages (from mkdocs-mermaid2-plugin->-r requirements.txt (line 6)) (1.15.1)
Requirement already satisfied: beautifulsoup4>=4.6.3 in ./venv/lib/python3.10/site-packages (from mkdocs-mermaid2-plugin->-r requirements.txt (line 6)) (4.12.3)
Requirement already satisfied: setuptools>=18.5 in ./venv/lib/python3.10/site-packages (from mkdocs-mermaid2-plugin->-r requirements.txt (line 6)) (59.6.0)
Requirement already satisfied: soupsieve>1.2 in ./venv/lib/python3.10/site-packages (from beautifulsoup4>=4.6.3->mkdocs-mermaid2-plugin->-r requirements.txt (line 6)) (2.5)
Requirement already satisfied: watchdog>=2.0 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (4.0.0)
Requirement already satisfied: ghp-import>=1.0 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (2.1.0)
Requirement already satisfied: pathspec>=0.11.1 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (0.12.1)
Requirement already satisfied: mergedeep>=1.3.4 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (1.3.4)
Requirement already satisfied: pyyaml-env-tag>=0.1 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (0.1)
Requirement already satisfied: click>=7.0 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (8.1.7)
Requirement already satisfied: packaging>=20.5 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (24.0)
Requirement already satisfied: pyyaml>=5.1 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (6.0.1)
Requirement already satisfied: mkdocs-get-deps>=0.2.0 in ./venv/lib/python3.10/site-packages (from mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (0.2.0)
Requirement already satisfied: charset-normalizer<4,>=2 in ./venv/lib/python3.10/site-packages (from requests~=2.26->mkdocs-material->-r requirements.txt (line 5)) (3.3.2)
Requirement already satisfied: urllib3<3,>=1.21.1 in ./venv/lib/python3.10/site-packages (from requests~=2.26->mkdocs-material->-r requirements.txt (line 5)) (2.2.1)
Requirement already satisfied: certifi>=2017.4.17 in ./venv/lib/python3.10/site-packages (from requests~=2.26->mkdocs-material->-r requirements.txt (line 5)) (2024.2.2)
Requirement already satisfied: idna<4,>=2.5 in ./venv/lib/python3.10/site-packages (from requests~=2.26->mkdocs-material->-r requirements.txt (line 5)) (3.7)
Requirement already satisfied: bracex>=2.1.1 in ./venv/lib/python3.10/site-packages (from wcmatch>=7->mkdocs-awesome-pages-plugin->-r requirements.txt (line 4)) (2.4)
Requirement already satisfied: six>=1.13.0 in ./venv/lib/python3.10/site-packages (from jsbeautifier->mkdocs-mermaid2-plugin->-r requirements.txt (line 6)) (1.16.0)
Requirement already satisfied: editorconfig>=0.12.2 in ./venv/lib/python3.10/site-packages (from jsbeautifier->mkdocs-mermaid2-plugin->-r requirements.txt (line 6)) (0.12.4)
Requirement already satisfied: python-dateutil>=2.8.1 in ./venv/lib/python3.10/site-packages (from ghp-import>=1.0->mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (2.9.0.post0)
Requirement already satisfied: platformdirs>=2.2.0 in ./venv/lib/python3.10/site-packages (from mkdocs-get-deps>=0.2.0->mkdocs>=1.1->mkdocs-autorefs->-r requirements.txt (line 3)) (4.2.1)

How to reproduce:
tmp.zip

# Initialize venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

1. Run page using mkdocs serve -w ./build/ --> diagram is shown
2. Extract page using mkdocs build and open it in the browser of your choice --> syntax error is shown instead

Thanks a lot for your assistance!
Best regards,
Dominik

[dominik4545]

Found and fixed it:
The documentation has an issue which just occurs when the site is exported.

1. You need to install the mkdocs-mermaid2-plugin
2. The configuration of the fence needs to be adjusted:

  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid

in addition to the plugins

plugins:
  - search:
      lang: en
  - mermaid2

[alexvoss]

Material has its own Mermaid integration that does not depend on the third party plugin. If you want to use the plugin then it is no wonder that the configuration needs to be different.

[squidfunk]

A minimal reproduction can save thousands of characters 😉

[dominik4545]

Now we're getting somewhere, I didn't stop to think that perhaps they're trying to run the index.html file from the filesystem and not through a server. mermaid.js isn't downloaded via the offline plugin, and it still has to be downloaded via the bundle.js 🤔 I can imagine some bug hidden there, as offline builds aren't the main focus when developing the theme.
I removed the offline plugin and the issue continued, so I added it again during the reproduction.

During the reproduction I figured out, the mermaid diagrams were gone as soon as I added the following two features:

theme:
  features:
    - navigation.instant
    - navigation.instant.progress

But I am wondering: If I try to build the website and host it somewhere, the instant loading could also be benefitial or is it not how it works?

[alexvoss]

Instant loading and the offline plugin don't work together. So, yes, you can expect that this will work as soon as you turn off the offline plugin and host your build on a server - fingers crossed.

[dominik4545]

Oh dear - sorry for wasting your time. I should probably read better 🙈

[alexvoss]

No worries. There is a lot of functionality and it is only human to miss things. Hope all goes well from here.