mkdocs-material: Refreshing page will show Syntax error in mermaid graph sometimes

Contribution guidelines

I’ve read the contribution guidelines and wholeheartedly agree

I’ve found a bug and checked that …

… the problem doesn’t occur with the mkdocs or readthedocs themes
… the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
… the documentation does not mention anything about my problem
… there are no open or closed issues that are related to my problem

Description

Refreshing page will show Syntax error in mermaid graph sometimes. This shows in the Official Docs for me. Also, using mkdocs serve/build reproduces the same bug.

Expected behaviour

Always show the correctly rendered MermaidJS graph.

Actual behaviour

Sometimes normal, while sometimes not.

Refreshing page but with cache disabled can solve this problem…

Steps to reproduce

Just keep refreshing the page.

Package versions

Doesn’t matter.

Configuration

Doesn't matter.

System information

Operating system: Mac OS / Windows.
Browser: Chrome / Firefox

About this issue

Original URL
State: closed
Created 3 years ago
Comments: 19 (15 by maintainers)

Links to this issue

Replace mermaid styles with a built-in theme (!3262) · Merge requests · GitLab.org / GitLab Docs · GitLab

Commits related to this issue

fix refresh page bug https://github.com/squidfunk/mkdocs-material/issues/3232 this issue was guidance to root case. Turn off nav.instant and js load order comeback to normal — committed to HOOTORO/afk.GG by HOOTORO a year ago

Most upvoted comments

Thanks for this discussion–it helped us diagnose a similar issue on the Kubernetes website. 🙇🏻

zacharysarah on May 27, 2022

@Guts You are welcome. Glad it helped!

orenwang on Nov 26, 2021

Thanks a lot @orenwang, this is exactly the problem that has been blocking us for a while: https://github.com/squidfunk/mkdocs-material/discussions/3056. Hurray, it’s finally fixed 🙏!

Guts on Nov 26, 2021

The fix was just released as part of 7.3.6-insiders-3.2.3.

squidfunk on Nov 20, 2021

I don’t think Mermaid runs async, but I do it the same way as I do MathJax which does use async 🤷🏻 :

Setup: https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/js/extra-loader.js#L30
Subscribe: https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/js/extra-loader.js#L55
Actual code: https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/js/uml.js
Loader included here: https://github.com/facelessuser/pymdown-extensions/blob/main/mkdocs.yml#L171
Config included here https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/html/libs.html#L2 which is, in turn, included here https://github.com/facelessuser/pymdown-extensions/blob/main/docs/theme/main.html#L5. I recently just bundled it as I have a plugin that patches all my repos with the customizations and I don’t really customize my Mermaid config per repo, so I just wanted it included directly in the theme.

I don’t know how much any of this info will help, but maybe there is something that stands out.

facelessuser on Nov 17, 2021

Potential fix in f8b74c207. My testing shows that this mitigates the issue. I’ll look into it again to search for a better solution when I find some time to refactor this part of the code. It’s really sad that Mermaid has such a bad API design.

squidfunk on Nov 17, 2021