super fences configuration prevents loading additional icon packs

[mgrubb]

I'm trying to get Mermaid's new architecture-beta diagram type working along with loading additional icon resources shown (here)[https://mermaid.js.org/syntax/architecture.html#icons].

I've created a javascript file to be used with the extra_javascript key in the mkdocs.yml file that calls the mermaid.registerIconPacks function from the Mermaid documentation referenced above.

When I have the superfences configuration set as referenced by the mermaid2 documentation as (here)[https://github.com/fralau/mkdocs-mermaid2-plugin?tab=readme-ov-file#additional-settings-for-the-material-theme] the icon packs won't load. When I remove the superfences configuration then the icon packs load as expected, but of course syntax highlighting breaks.

I've tried adding the registerIconPacks call directly in the plugin to have it in the same script block but that doesn't seem to make a difference. I've also tried explicitly calling initialize in my extra_javascript file while having the superfences config enabled but that didn't seem to make a difference. Though when using the superfences configuration it doesn't appear as though mermaid.initialize() is called at all. I could not find any reference to window.mermaidConfig being used after it is set by the script tag created by the plugin when using superfences, so I'm not clear how that works.

Any advice on how to get this to work with superfences enabled?

[github-actions]

Thank you for your contribution! This is very appreciated.

[fralau]

The problem seems to be, here, in the Javascript code, possibly in relation to the HTML tags that enclose the javascript (<pre><code> versus <div>) 🤔

It is important to keep in mind that the plugin does not do any Javascript, except for inserting calls to the library and initialization sequences.

1. First (just to make sure) are you using the custom fence recommended?
2. Secondly, I would confirm that the same version of the Javascript library is being used in all test cases.
3. If that doesn't solve, I would get the MkDocs-Mermaid2 plugin out of the equation. You could look at the HTML/Javascript pages produced, and try to reduce the issue to a mininum reproducible case. You might want to tweak it around, with the eye firmly on the Mermaid documentation.
4. If that doesn't solve you could submit to Mermaid team as a question, asking "what is this HTML/Javascript code doing incorrectly"?
5. It could be that the diagnosis would help you solve your problem. But if it appears that the plugin could or should be corrected, then you could put forward the diagnosis in this issue, showing what the HTML code is, and what it should have been.

[mgrubb]

So the problem doesn't appear to be with Mermaid or this plugin. It looks like Material theme for Mkdocs has added support for Mermaid since v8.2.0. Their implementation seems to be interfering with this plugin. I switched to the Cinder theme and was able to use this plugin and load the custom icon packs without any issues.

[fralau]

Thanks, and it's good that you got it working.

If you still wish to use Material, you could try to use its own recommended custom fence (just in case, to see what happens)?

If all else fails, you might want to open a discussion on Material's github repo?

I'm interested in that issue, since I am in the process of impletementing test cases for Superfences on the Mermaid2 plugin, using Mkdocs-Test.

(I'm putting @squidfunk in copy, just in case.)

[squidfunk]

You don't need to use our integration, which is targeted towards more consistent look and feel but might make more advanced Mermaid.js functionality harder to use. You can always use a custom integration, just don't add the mermaid CSS class in your custom fence, which is what Material is looking for.

We currently have no plans to add further functionality to our Mermaid integration.

[mgrubb]

@squidfunk Would it be possible to add the ability to disable the Material mermaid integration altogether? If I'm understanding you correctly you're saying that if mermaid2 were configured to use a different query selector than .mermaid, and the custom fence output that different class on it's generated element then the Material integration mermaid wouldn't interfere with the mermaid2 plugin. Did I get that correct? @fralau would this be possible to do without modifications to mermaid2?

Thanks to both of you for your attention to this.

[mgrubb]

So after some quick testing I got this working:
mkdocs.yml

plugins:
  - search
  - mermaid2:
      version: 11.4.0
      arguments:
        securityLevel: 'loose'
        startOnLoad: false

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

extra javascript file:

import mermaid from 'https://unpkg.com/[email protected]/dist/mermaid.esm.min.mjs'
document$.subscribe(function() {
  console.log("Initialize third-party libraries here")
  mermaid.registerIconPacks([
    {
      name: 'logos',
      loader: () =>
        fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()),
    },
    {
        name: 'aws',
        loader: () =>
        fetch('/assets/js/aws-logos.json').then((res) => res.json()),
    }
  ])
  mermaid.run({querySelector: '.diagram'});
});

That loads the extra icon packs, and still enables syntax highlighting.

Edit:
After looking at the generated HTML, this caused mermaid2 to not generate a javascript tag, and in fact I was able to comment out the mermaid2 plugin altogether and this change caused Material to do what I wanted.

[squidfunk]

@squidfunk Would it be possible to add the ability to disable the Material mermaid integration altogether?

As already mentioned in #111 (comment), just use another class, as you did in #111 (comment) with diagram. The Mermaid integration already is opt-in, so no need to add another option to disable it ☺️

[fralau]

@squidfunk Thanks for your help!

@mgrubb Is my understanding correct that you used the extra_javascript parameter? Do you feel it is a case where the default settings of the plugin were not adequate?

[mgrubb]

I used the extra_javascript parameter in order to call the mermaid.registerIconPack() function. I'm not entirely sure how common this use case will be. I don't know if other diagram types can use those icon packs as well, or if this is something specific to the Architecture diagram type. I'm new to both the mkdocs and mermaid ecosystems.
It might be nice to be able to do something like:

plugins:
  - mermaid:
      iconPacks:
        - name: logos
          url: https://unpkg.com/.....

And have the plugin generate the call to mermaid.registerIconPacks()

[fralau]

@mgrubb Thanks for you useful feedback! I agree with you that this use case might not be common, and does not warrant a development for the moment.

However, it has one merit; it shows that the extra_javascript parameter in the config file still has its own use.

Here is, for the record, an important point concerning Mkdocs-Mermaid2:

If Mkdocs-Mermaid2 detects a name of library that contains the word mermaid, it will deactivate its own automatic/manual insertion mecanism and fall back on the standard mechanism of MkDocs.
(Documentation)

This is what allowed your workaround to work, and I am glad that I took that precaution!

Take-away: MkDocs-Mermaid2 should continue to support extra_javascript parameter, as a failsafe mechanism.

[fralau]

Finally @squidfunk: this is the opportunity to say that MkDocs, aside of being a good piece of software, owes some of its success to a friendly community of people with diverse backgrounds and competences.

[fralau]

TODO: update documentation, to clarify the role of extra_javascript as a failsafe mechanism.

[fralau]

See https://mkdocs-mermaid2.readthedocs.io/en/latest/library/#using-extra_javascript