How to mermaid.registerIconPacks in MkDocs

[rmorshea]

I can't seem to figure out how to properly register icons with mermaid as shown in these code snippets. I just get a bunch of "?" instead of the expected icons:

I attempted to add the following to my mkdocs.yml file:

extra_javascript:
    - https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs
    - path: js/register-mermaid-icons.js
      type: module

Where js/register-mermaid-icons.js contains:

import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";

mermaid.registerIconPacks([
    {
        name: "simple-icons",
        loader: () =>
            fetch("https://unpkg.com/@iconify-json/logos/icons.json").then((res) =>
                res.json()
            ),
    },
]);

I've confirmed that the JS is getting executed and that it doesn't error, but it doesn't change the outcome shown above.

My best guess is that either I'm importing a different mermaid than the one used by this extension or that registerIconPacks() is getting called after the markdown content has already been transformed into the chart.

Related question here: https://github.com/orgs/mermaid-js/discussions/5953#discussioncomment-10919748

[facelessuser]

I don't directly offer Mermaid support, what I do offer is my original notes on how I implemented what I use in my own documents, and why I do what I do: https://facelessuser.github.io/pymdown-extensions/extras/mermaid.

I'm not an expert on everything Mermaid, nor have I tried all the features in Mermaid, nor am I certain my approach will be compatible with everything in Mermaid.

I don't normally do this, so this will be about as much assistance I will provide, but I dropped the icon loading snippet into this file: https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/js/uml.js

diff --git a/docs/src/js/uml.js b/docs/src/js/uml.js
index 139ef215..57571fc8 100644
--- a/docs/src/js/uml.js
+++ b/docs/src/js/uml.js
@@ -14,6 +14,8 @@
  */
 export default async className => {
 
+  let iconsLoaded = false
+
   // Custom element to encapsulate Mermaid content.
   class MermaidDiv extends HTMLElement {
 
@@ -95,6 +97,19 @@ export default async className => {
   const config = (typeof mermaidConfig === "undefined") ?
     defaultConfig :
     mermaidConfig[scheme] || (mermaidConfig.default || defaultConfig)
+
+  if (!iconsLoaded) {
+    mermaid.registerIconPacks([
+      {
+        name: "simple-icons",
+        loader: () =>
+          fetch("https://unpkg.com/@iconify-json/logos/icons.json").then(res =>
+            res.json()
+          )
+      }
+    ])
+    iconsLoaded = true
+  }
   mermaid.initialize(config)
 
   // Find all of our Mermaid sources and render them.

I then dropped the example in my docs (I use the diagram specifier instead of mermaid):

```diagram
architecture-beta
    service left_disk(disk)[Disk]
    service top_disk(disk)[Disk]
    service bottom_disk(disk)[Disk]
    service top_gateway(internet)[Gateway]
    service bottom_gateway(internet)[Gateway]
    junction junctionCenter
    junction junctionRight

    left_disk:R -- L:junctionCenter
    top_disk:B -- T:junctionCenter
    bottom_disk:T -- B:junctionCenter
    junctionCenter:R -- L:junctionRight
    top_gateway:B -- T:junctionRight
    bottom_gateway:T -- B:junctionRight
```

And it worked fine:

I don't know what theme you are using in MkDocs, I don't know if it has code in it to automatically load Mermaid diagrams. I don't know what scripts you may or may not be running to try and do so. I don't know if there is trouble with your setup running the icon registration before your MkDocs setup processes your diagrams. My example above inserted the necessary code directly into my special loader stuff. Since I do not directly support Mermaid, I don't have the bandwidth to debug people's Mermaid setup. The only assistance I provide is the linked document above.

Hopefully, this helps some.

[rmorshea]

Ah, I was under the impression that there was some special handling of mermaid code-blocks in this markdown extension. The burden for making this easier almost certainly falls on the MkDocs theme since, if the user hasn't loaded mermaid.js, the theme would have.

For others coming here, the solution is (and feel free to correct me if I'm wrong) to declare a custom code fence with someClass you can query for later (e.g. diagram as in the linked examples above). Import the mermaid JS API and then run something like:

// there may be better ways to do this - haven't read through enough of the docs to be sure
mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  querySelector: '.someClass',
});

I'm assuming that this globalReset() call is meant to deal with a theme that has already loaded mermaid once. Dealing with a theme is also the reason to use some class besides mermaid in order to avoid conflicting with any render pass mermaid does when it's rendered by a theme.

[rmorshea]

One other note, the sample diagram I was interested in was:

architecture-beta
    group api(logos:aws-lambda)[API]

    service db(logos:aws-aurora)[Database] in api
    service disk1(logos:aws-glacier)[Storage] in api
    service disk2(logos:aws-s3)[Storage] in api
    service server(logos:aws-ec2)[Server] in api

    db:L -- R:server
    disk1:T -- B:server
    disk2:T -- B:db

Seems like the anchor I linked to wasn't scrolling to the right position to make that clear.

[facelessuser]

In that case, what I'm doing doesn't make those icons load either. I have no idea why it doesn't work.

[facelessuser]

Oh, never mind, I was specifying simple-icons, but your example uses logos. When I set name to logos in the register function instead of simple-icons it works because the diagram is referencing logos:aws-aurora. So it is a user error.