Regarding adding zenuml to material for mkdocs #8407

vcdemy · 2025-08-21T23:35:30Z

vcdemy
Aug 21, 2025

Hi all,

I am trying to add mermaid zenuml to material for mkdocs, but the zenuml diagram was not shown as expected.

What I did is as follows:

Create mermaid.mjs to register zenuml
Add this mermaid.mjs from extra_javascript section in mkdocs.yml
write a simple index.md to test zenuml

The code is as follows:

docs/javascript/mermaid.mjs,

(Actually I modified the code from here -> diagram customization )

import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/[email protected]/dist/mermaid-zenuml.esm.min.mjs';

await mermaid.registerExternalDiagrams([zenuml]);

mermaid.initialize({
    startOnLoad: true,
    sequence: { 
           actorFontSize: "16px", // Hack: mitigate https://bit.ly/3y0NEi3 
           messageFontSize: "16px", 
           noteFontSize: "16px"}
    });

window.mermaid = mermaid;

In mkdocs.yml:

extra_javascript:
  - javascript/mermaid.mjs

In index.md:

# Testing UML

```mermaid
zenuml
    title Declare participant (optional)
    @Actor Bob
    Alice
    Alice->Bob: Hi Bob
    Bob->Alice: Hi Alice
```

The result is as follows:

Does anyone know what I missed?

Thanks!

vcdemy · 2025-08-21T23:42:36Z

vcdemy
Aug 21, 2025
Author

By the way, I tested the same code in HTML5!

index.html

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <pre class="mermaid">
        zenuml
        title Annotators
        @Actor Alice
        @Database Bob
        Alice->Bob: Hi Bob
        Bob->Alice: Hi Alice
    </pre>
    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
      import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/[email protected]/dist/mermaid-zenuml.esm.min.mjs';
      await mermaid.registerExternalDiagrams([zenuml]);
      mermaid.initialize({ startOnLoad: true });
    </script>
  </body>
</html>

The result is as follows:

Thanks!

0 replies

kamilkrzyskow · 2025-08-23T14:23:01Z

kamilkrzyskow
Aug 23, 2025
Collaborator

Hello @vcdemy,
have you tried this other approach at injecting the Mermaid modules?

Mermaid built in icons do not load #7723 (comment)

This is my only lead, as I personally never used Mermaid module extensions.

I only did some Mermaid style injection via patching the minified JS but this doesn't really apply to enabling modules or maybe I'm missing something 🤔

Mermaid with Icons #6778 (reply in thread)

4 replies

vcdemy Aug 23, 2025
Author

Hi @kamilkrzyskow,

Thanks for the information!
However, it does not seem to resolve the zenuml issue. The problem does not seem to be caused by the icon.

I tested though. :)

mermaid.mjs

import mermaid from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.esm.min.mjs';
import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/[email protected]/dist/mermaid-zenuml.esm.min.mjs';

await mermaid.registerExternalDiagrams([zenuml]);

mermaid.initialize({
    startOnLoad: true,
    sequence: { 
           actorFontSize: "16px", // Hack: mitigate https://bit.ly/3y0NEi3 
           messageFontSize: "16px", 
           noteFontSize: "16px"}
    });

window.mermaid = mermaid;

index.md

```mermaid
zenuml

    title Declare participant (optional)
    @Actor Bob
    Alice
    Alice->Bob: Hi Bob
    Bob->Alice: Hi Alice
```

```mermaid
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
```

Result:

Adding the registering icon part:

mermaid.mjs

import mermaid from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.esm.min.mjs';
import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/[email protected]/dist/mermaid-zenuml.esm.min.mjs';

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

await mermaid.registerExternalDiagrams([zenuml]);

mermaid.initialize({
    startOnLoad: true,
    sequence: { 
           actorFontSize: "16px", // Hack: mitigate https://bit.ly/3y0NEi3 
           messageFontSize: "16px", 
           noteFontSize: "16px"}
    });

window.mermaid = mermaid;

Result:

kamilkrzyskow Aug 24, 2025
Collaborator

Thanks for following up. I run it locally with the example from the other thread that allows to initialize the mermaid object from the theme itself and got the same results, so I debugged further.
The issue turns out to be the shadow root, which separates the global JS namespace and CSS from inside the shadow root.

mkdocs-material/src/templates/assets/javascripts/components/content/mermaid/index.ts

Line 119 in fdd6fc6

const shadow = host.attachShadow({ mode: "closed" })

First I checked if open-mode shadowRoot would help, it didn't, so I added the extra CSS manually

And it worked.

Rendered

So now we have the question how to inject the CSS properly?
I don't know what's the best approach to handle this. The themeCSS is part of the bundle.js stored in a variable, so in theory you can inject more CSS into it using the approach from my other comment.

mkdocs-material/src/templates/assets/javascripts/components/content/mermaid/index.ts

Line 95 in fdd6fc6

themeCSS,

But that's on the Python docs build step, so you'd have to extract the CSS from the mjs file and then inject it into bundle.js

Or replace the logic of the initialization, but can you initialize it with all CSS involved? idk 🤔

Last option can be forking the theme and removing the shadowRoot but this could lead to issues with sullied id namespace.

Monkey patching as always seems better in my eye than proper development, but I'm biased 😅

vcdemy Aug 24, 2025
Author

Hi @kamilkrzyskow,

This is cool. Did you manually modify the CSS using DevTools? Where do you get the CSS? I meant the one you added manually.

Thanks!

kamilkrzyskow Aug 25, 2025
Collaborator

Yes, I added it in DevTools, I just copied the <style> from the bottom of <head> section that gets added via the mjs file:
https://cdn.jsdelivr.net/npm/@mermaid-js/[email protected]/dist/chunks/mermaid-zenuml.esm.min/zenuml-definition-XJYTECJ4.mjs

How to add it permanently requires more digging/tinkering, as I mentioned in the second part of the comment.

vcdemy · 2025-08-26T09:14:13Z

vcdemy
Aug 26, 2025
Author

Hi @kamilkrzyskow,

Hmmm... I am not very familiar with frontend stuff... so I temporarily used the following method as a workaround.

In mkdocs.yml

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_div_format

extra_javascript:
  - js/mermaid.mjs

The fence_div_format is to convert the mermaid code block to div block, instead of mermaid diagram directly.

In docs/js/mermaid.mjs

import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/[email protected]/dist/mermaid-zenuml.esm.min.mjs';

await mermaid.registerExternalDiagrams([zenuml]);

mermaid.initialize({
    startOnLoad: true,
    sequence: { 
           actorFontSize: "16px", // Hack: mitigate https://bit.ly/3y0NEi3 
           messageFontSize: "16px", 
           noteFontSize: "16px"}
    });

window.mermaid = mermaid;

Then, let the new mermaid module convert the div block to mermaid diagrams.

This worked fine. It's just that you will see the raw text before the diagram shows up.

Therefore, I hide the div.mermaid by adding div.mermaid {color:transparent;}

That is, create a extra.css

div.mermaid {color:transparent;}

And add the following to mkdocs.yml

extra_css:
  - css/extra.css

Now it looks better.

0 replies

Uh oh!

Regarding adding zenuml to material for mkdocs #8407

Uh oh!

Uh oh!

vcdemy Aug 21, 2025

Replies: 3 comments · 4 replies

Uh oh!

vcdemy Aug 21, 2025 Author

Uh oh!

kamilkrzyskow Aug 23, 2025 Collaborator

Uh oh!

vcdemy Aug 23, 2025 Author

Uh oh!

Uh oh!

kamilkrzyskow Aug 24, 2025 Collaborator

Uh oh!

vcdemy Aug 24, 2025 Author

Uh oh!

kamilkrzyskow Aug 25, 2025 Collaborator

Uh oh!

Uh oh!

vcdemy Aug 26, 2025 Author

vcdemy
Aug 21, 2025

Replies: 3 comments 4 replies

vcdemy
Aug 21, 2025
Author

kamilkrzyskow
Aug 23, 2025
Collaborator

vcdemy Aug 23, 2025
Author

kamilkrzyskow Aug 24, 2025
Collaborator

vcdemy Aug 24, 2025
Author

kamilkrzyskow Aug 25, 2025
Collaborator

vcdemy
Aug 26, 2025
Author