What exactly trigger MermaidJS diagrams rendering ?

[Thiti517]

I'm working on a printed version of my documentation site and need to render all content before generating the final document. This includes elements like MermaidJS, MathJax, content tabs, admonitions, and others.

For most of these, I can use a headless browser to load the page, allowing the JavaScript scripts to execute and transform the content as expected. However, MermaidJS is the only one that does not render during this process. Instead of generating diagrams, the document retains the raw MermaidJS code.

Upon inspecting the mkdocs-material code, I noticed that all TypeScript files are bundled into an IIFE (Immediately Invoked Function Expression), which means I can't directly access them. However, when I manually copy the JavaScript function responsible for rendering MermaidJS diagrams into a separate JS file, my headless browser successfully renders the diagrams.

I want to understand:

• What exactly triggers MermaidJS to render diagrams in the mkdocs-material JS bundle?
• Why does this process not execute correctly in a headless browser?
• Is there a way to manually trigger MermaidJS rendering without modifying the bundled script?

I'm not sure if i understood the typescript code and bundling process correctly so i could be wrong in my research.

Any help would be greatly appreciated.

[kamilkrzyskow]

Hi @Thiti517,
please elaborate on the "render all content before generating the final document". Mermaid is mounted like the rest of the elements:

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

  Line 117 in 44c3b56

  .map(child => mountMermaid(child)),

However, Mermaid is mounted in a closed ShadowRoot, so depending on how you detect that an element is available on the website, then the separate root layer might prevent that:

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

  Line 119 in 44c3b56

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

• Mermaid with Icons #6778

[Thiti517]

Basically, I'm trying to ensure that all JavaScript-generated content is fully rendered before mkdocs-with-pdf builds a PDF from the HTML site. mkdocs-with-pdf is an old, apparently unmaintained MkDocs plugin, but it's still relevant for me and my coworkers.

So, to go back to what I found in this response and my research, I had two issues preventing me from seeing rendered diagrams.

First, I needed to correctly open the HTML file in the headless browser so it could load local scripts and CSS. This issue was preventing the bundled JS from being loaded and executed. Now, it loads correctly. I had completely overlooked this possibility, assuming the headless browser would resolve the absolute path using the given relative path and CWD.

Second, the ShadowRoot is indeed preventing my headless browser from "seeing" the rendered MermaidJS diagrams and including them in the final HTML document. I'm currently learning more about ShadowRoot and exploring ways to capture the rendered diagrams for my printed final document. However, I now fully understand the importance of keeping the ShadowRoot to prevent conflicts between the diagrams and the Material theme (main content CSS).

With this new information, my three questions from the first post have become irrelevant, as the Mermaid rendering process does occur but is not directly manipulable/accessible by the headless browser itself.

I will then mark the comment as answer since it pointed me to the real problem i'm facing.

[kamilkrzyskow]

I see that mkdocs-with-pdf opens up a headless chrome and saves the HTML to later process it on the Python end with BeautifulSoup?
I initially imagined a simple headless browser which pressed Ctrl + P 😅, but I now see that the issue is a bit more involved.

The closed mode of the shadow root is what's preventing to see and modify what's inside it. Like mentioned in the linked discussion:

• Mermaid with Icons #6778 (reply in thread)
• Mermaid with Icons #6778 (reply in thread)

you can change the mode to open, with the "hack" hook above, which would preserve the root separation, while allowing to see inside and modify the insides.

On the PymdownX website the mode is open, and it does use the material theme, so in theory it should work for everyone, but I never got around to testing it.

• https://facelessuser.github.io/pymdown-extensions/extras/mermaid/

And now there is a feature freeze, and no changes to Mermaid will be done for now:

• feat: add ability to control mermaid icon packs #7929