Use HTML anchors in Mermaid node labels / initialize Mermaid with loose security

[pawamoy]

I'm playing with Mermaid, trying to display a class inheritance diagram (flowchart) in mkdocstrings-python.

Here's what I currently have:

{% macro edges(class) %}
  {% for base in class.resolved_bases %}
    {{ base.path }} --> {{ class.path }}
    {{ edges(base) }}
  {% endfor %}
{% endmacro %}

<pre class="mermaid">
  <code>
    flowchart TD
    {{ class.path }}[<span data-autorefs-optional-hover="{{ class.path }}">{{ class.name }}</span>]
    {% for base in class.mro() %}
    {{ base.path }}[<span data-autorefs-optional-hover="{{ base.path }}">{{ base.name }}</span>]
    {% endfor %}
    {{ edges(class) }}
  </code>
</pre>

The autorefs spans are transformed at the end of the MkDocs build, giving something like:

<pre class="mermaid">
  <code>
    flowchart TD
    mkdocstrings.handlers.base.BaseHandler[<a href="https://mkdocstrings.github.io/reference/mkdocstrings/handlers/base/#mkdocstrings.handlers.base.BaseHandler" title="mkdocstrings.handlers.base.BaseHandler">BaseHandler</span>]
    <!-- other nodes -->
    <!-- edges, nothing fancy here -->
  </code>
</pre>

Then, when loading the page in the browser, Mermaid transforms the pre code into a proper SVG diagram.

However there several issues here:

1. Mermaid does not allow arbitrary HTML anymore in node labels. I'd have to initialize Mermaid with security: "loose" and htmlLabels: true to allow it. Is it possible? Or is it already the case?
2. Even HTML labels enabled, the syntax is invalid: the HTML label should be wrapped in double-quotes.
3. Even if I wrap it in double-quotes, the link generated by autorefs uses double-quotes too (around href, title, etc.), so this breaks the syntax (I wish Mermaid supported wrapping with single-quotes...)

I know about Mermaid's interaction capabilities, and since callbacks can receive the node ID, I could probably hack something together by rendering links in a hidden divs, collecting them in javascript and pre-defining callbacks that redirect to the right pages, but that feels a bit heavy and not super elegant.

Any hints or idea on how to make all this work 🤔?

[pawamoy]

OK this is much better with click callbacks actually.

<div style="display: none">
  <span data-autorefs-optional-hover="{{ class.path }}" id="mermaid-{{ class.path }}">{{ class.name }}</span>
  {% for base in class.mro() %}
    <span data-autorefs-optional-hover="{{ base.path }}" id="mermaid-{{ base.path }}">{{ base.name }}</span>
  {% endfor %}
</div>

<pre class="mermaid"><code>
flowchart TD
{{ class.path }}[{{ class.name }}]
{% for base in class.mro() %}
{{ base.path }}[{{ base.name }}]
{% endfor %}

{{ edges(class) }}

click {{ class.path }} mermaidClick "{{ class.path }}"
{% for base in class.mro() %}
click {{ base.path }} mermaidClick "{{ base.path }}"
{% endfor %}
</code></pre>

<script>
  function mermaidClick(nodeID) {
    console.log("Clicked on " + nodeID);
    window.location.href =  document.getElementById("mermaid-" + nodeID).href;
  }
</script>

However no event is bound on nodes. I suppose it's because the security option is set to strict and not loose? 🤔

[pawamoy]

So, in simple words, Mermaid's click is not supported within Material for MkDocs, right? And the solution you mention is probably this one: https://github.com/facelessuser/pymdown-extensions/blob/87e649dc00fa3d7909d02f0f6109e6eafb712a70/docs/src/js/uml.js#L29. I dare not enter this territory (and I'm not even sure it's a valid solution for a MkDocs plugin).

[pawamoy]

you can't access it from outside with JavaScript

Note that in my case it's rather the opposite: it is Mermaid's code that is supposed to access the outside (the mermaidClick callback). Not sure this make any difference though.

Is it possible to somehow define my callback within the diagram's shadow root then, so it can access it 🤔?

[pawamoy]

So, even if I do this:

click {{ class.path }} href "javascript:mermaidClick('{{ class.path }}')"

...the node is marked as clickable but there's no event or href on it. I don't understand why this doesn't work. I don't think the shadow root as anything to do with this? Surely the renderer doesn't check if mermaidClick in the href attribute value javascript:mermaidClick('id') is a valid function in the current context? So there's something else that prevents the click feature entirely? I'm a bit lost here 😅

[kamilkrzyskow]

And the solution you mention is probably this one...

Yes

and I'm not even sure it's a valid solution for a MkDocs plugin

Consult the Mermaid-2 plugin then, never seen their code 😅

Note that in my case it's rather the opposite: it is Mermaid's code that is supposed to access the outside (the mermaidClick callback). Not sure this make any difference though.

Then perhaps changing the mode from closed to open might still not help in this instance, as the shadow root, is still a root.
MkDocs Material uses the Mermaid library to compile the diagrams and puts the generated HTML into a shadow root, so the inside isn't aware of the outside and the IDs aren't mixed up, as many diagrams on one page can share the same IDs.

I'm no expert on the topic, but I know that once the mode is open we'd be able to inject CSS into the shadow root, so there is a chance that you could create a callback in the global root and pass it over to the shadow root as well, you know as a pointer reference like in Python, but this might not work at all as the root inside might not access things by reference, as the scope is different.

I guess injecting the whole mermaid.js script tag into the open shadow root could work 🤔

Is it possible to somehow define my callback within the diagram's shadow root then, so it can access it

You can temporarily test things out with this hacky hook and add your own stuff like the mermaid.js script tag inside the shadow root etc.:

• Mermaid with Icons #6778 (reply in thread)

and maybe rewrite it into a safer alternative in the process 😸:

• Disabling media pause when switching content tabs. #6844 (reply in thread)

[pawamoy]

OK I'm definitely out of my depth here 😅 Thanks a lot for all the info @kamilkrzyskow!! ❤️
I'll check these links and report back if I manage to make it work 🙂

[pawamoy]

OK, instead of entering shadowland, where hyenas would be waiting for my poor lion cub self 🦁, I went with yet another approach.

By the time the HTML is rendered from Markdown, I have both the diagram contents, and the links for each node. So I just need to update the diagram code to add these links in the right place (in the click href). I use a regex replace. This is working fine 🙂

let diagram = document.getElementById('mermaid-diagram-{{ class.path }}');
diagram.innerHTML = diagram.innerHTML.replace(/click ([\w.]+) href ""/g, function(match, nodeID, offset) {
  let link = document.getElementById("mermaid-link-" + nodeID).href;
  return `click ${nodeID} href "${link}"`
});

I could not do this in one go because the code that generates the correct link runs at the end of the MkDocs build, in the on_post_build event.

Thank you again for your help @kamilkrzyskow! Feel free to close if that's you usually do with resolved discussions 🙂

[kamilkrzyskow]

Wait what :o, if innerHTML can be edited then perhaps my suggestion in (#6778) of opening up the root is unnecessary. I'll try to inject the CSS this way.

[kamilkrzyskow]

No dice, the injected CSS in the pre tag will just be removed, should've guessed.
Still, congrats on getting it to work, though now I will admit I'm not sure if the solution needs to be in JavaScript, though it's probably cleaner than the respective solution in Python (storing the mermaid pages / links etc. and here you can just query the document).

The theme also exposes a component observable that is triggered when processing components, including the mermaid pre blocks. But probably your plugin does have to be more general and not just focus on the theme 🤔

component$.subscribe(data => {
    if (!data.hasOwnProperty("ref")) return;
    
    const ref = data["ref"];
    
    if (!ref.classList.contains("mermaid")) return;
   
    console.log(ref.innerHTML);
});

[pawamoy]

Yep, exactly, I'd like to stay theme-agnostic 🙂