mermaid 10 is incompatible

[krisztianpinter]

the documentation says you can use the latest version.

https://github.com/fralau/mkdocs-mermaid2-plugin#explicit-declaration-of-the-mermaid-library "For the latest version:"

this is no longer true. 10.0.0 introduces a breaking change, and the min.js file is no longer available (ESM only).

unfortunately unpkg recognizes the new version, and redirects to it. but the file itself is missing.

https://unpkg.com/mermaid/dist/mermaid.min.js -> 302 to 10.0.0

https://unpkg.com/[email protected]/dist/mermaid.min.js -> 404

maybe it would be worthwhile to remove this from the doc, or even add an explicit warning not to omit the version.

[github-actions]

Thank you for your contribution! This is very appreciated.

[maxbrokman]

Hi @fralau

To elaborate here –

From v10 mermaid no longer distributes a js file that exposes mermaid to the window. They instead distrubte an esm module that must be loaded differently on the frontend. See discussion here mermaid-js/mermaid#3590

For those of us using latest as referenced in the readme the release of mermaid 10 breaks the plugin because there is no longer a mermaid.min.js available to load.

I'm not a frontend / javascript person so forgive any errors here!

With the move to ESM only mermaid is now distributed as an esm module see here

Instead of being able to include mermaid through <script src="..."> one now has to explicitly import mermaid through use of

<script type="module">
import mermaid from "https://unpkg.com/[email protected]/dist/mermaid.esm.min.mjs"
mermaid.initialize()
</script>

I have made some changes to the plugin to support loading mermaid via a module if the requested version is >= 10. This will unfortunately break including mermaid via extra_javascript but that doesn't seem addressable without changes to mkdoc itself.

See https://github.com/laterpay/mkdocs-mermaid2-plugin/tree/esm_support / #72

[fralau]

Thanks for the great explanation! It seems indeed something important for the future of mkdocs-mermaid2, since it appears that the extra_javascript feature of mkdocs will no longer work.

[maxbrokman]

End users could probably still use extra_javascript by including something like

docs/js/mermaidloader.js

import mermaid from "https://unpkg.com/[email protected]/dist/mermaid.esm.min.mjs"
mermaid.initialize()

via

extra_javascript:
    - js/mermaidloader.js

Which could be added to the readme.

Alternatively you could remove the recommendation to do this to pull latest mermaid and point people to configuring the version for the plugin via its settings.

My PR allows use of mermaid 10 through the plugin itself rather than extra_javascript, I can make some changes to the readme if that would be helpful: #72

[maxbrokman]

@fralau have you had a chance to look at this PR #72

[fralau]

Hi, yes. There will be a little work to put this together (full concept + documentation). Thanks for your patience.

[fralau]

I reopened #72 , let's see what we do about it.

[fralau]

New version of mkdocs-mermaid2 (1.1.0-alpha) shoud solve it.

Could you please test it for yourself?

[MolenAtFuse]

for anyone else still using the old version, you can use the .min.js file from jsdelivr:

extra_javascript:
    - https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js