Handle module style inclusion of local Mermaid v10 library

[frank-lenormand]

Hi,

This is a follow-up to #90.

It’d be nice to be able to pick how the library passed to the javascript option will be imported.

As of now, there’s support only for the regular <script src="…" /> type of import, which works with Mermaid ≤ v9.

Mermaid v10 uses a module, which requires a different style of import (untested):

<script type="text/javascript">
    import mermaid from "<local_path_to>/mermaid.esm.min.mjs"
    mermaid.initialize()
</script>

Thanks!

[fralau]

The current version does support both, according to the extension.

[frank-lenormand]

Indeed, I missed that.

However, still in the spirit of rendering diagrams offline, it seems that v9 is still being loaded off of Unpkg.

In the dev tools, I see:

200 http://127.0.0.1:8000/site/js/mermaid.min.mjs 200 http://127.0.0.1:8000/site/js/mermaid-d733041c.js 200 https://unpkg.com/[email protected]/dist/mermaid.min.js

Configuration:

mkdocs.yml

- mermaid2:                                                               
    arguments:                                                            
      theme: |                                                            
        ^(JSON.parse(__md_get("__palette").index == 1)) ? "dark" : "light"
    javascript: js/mermaid.min.mjs                                        

docs/js

mermaid-10.4.0.min.mjs                   
mermaid-d733041c.js                      
mermaid.min.mjs -> mermaid-10.4.0.min.mjs

$ cat mermaid-10.4.0.min.mjs
import { b9 as f } from "./mermaid-d733041c.js";
export {
  f as default
};

HTML code generated (in a sub-directory, may be irrelevant though):

<script type="module">import mermaid from "../js/mermaid.min.mjs"; mermaid.initialize();
window.mermaidConfig = {default: {
    theme: (JSON.parse(__md_get("__palette").index == 1)) ? "dark" : "light",
    startOnLoad: false
}};</script>

[fralau]

The HTML generated seems correct? 🤔

(I do not know exactly what the dev tools report... could be what's in the cache?)

[frank-lenormand]

I always disable caching and hit ctrl+r to reload the page.

Here is what I see:

I figured the code had a rollback mechanism, or maybe the Mermaid library itself does, but I haven’t checked either.

[fralau]

I am not sure what happens, but the HTML looks fine to me? The best thing to do, would be to use mkdocs build and see directly what is in the HTML file, without going through the web server.

[frank-lenormand]

The line that loads the library from Unpkg comes from the bundle (site/assets/javascripts/bundle.78eede0e.min.js).

I have the following in my configuration, which is the root cause of the behaviour:

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

I added these lines after reading the associated documentation page:

https://mkdocs-mermaid2.readthedocs.io/en/latest/superfences/#usage-for-the-material-theme

If I remove this bit of configuration, Mermaid explodes telling me there’s a syntax error in my diagrams. I don’t know if v10 is retro-compatible with v9, I assumed it was. But the library is fully loaded off the local directory.

Any suggestions of what the best next move is?

[libukai]

In fact, the configuration provided by the author seems to be incorrect. If you want to use the V10+ version, the value of the "format" attribute should be: !!python/name:mermaid2.fence_mermaid

for example, we can use the mindmap gram now!

[fralau]

Hmm... there seems to be something there. In need to check whether it's the expected behavior or not.

[libukai]

You can also take a look at the example of a user configuration you provided here. The value of "format" must be set to !!python/name:mermaid2.fence_mermaid in order to take effect in the material theme.

[fralau]

Good point. There is indeed an inconsistency with the paragraph specifically written on Material, which quotes two requirements:

1. The use of the Superfences extension.
2. To use the default <pre class="mermaid"><code> representation, and not the <div class="mermaid"> representation used by mkdocs-mermaid2. This is achieved by using the fence_mermaid_custom function.

This needs to be sorted out: key question is, why that change of representation of the HTML code, in relation to Material. I don't remember what problem I was solving when I introduced it into the code.

On condition that the issues/code documentation were kept sufficiently well on Github (that's the opportunity to test it), one should be able to follow the trail.