Enable comments or annotations for mermaid diagrams in Material for MKDocs site

[chrisdburr]

Material for MKDocs is the static-site generator that is used to build the Assurance Platform documentation site.

It natively supports mermaid diagrams, which is great!

However, I'm trying to see if there is a way to also make use of another feature that is also built-in to Material for MKDocs: annotations.

Annotations are simple tool-tips, which would be an excellent way to add comments to any mermaid diagrams in the documentation. For instance, adding an explanation to a graphic of an assurance case. However, there doesn't appear to be an easy way to achieve this.

For instance, the following doesn't work, because it (unsurprisingly) throws a mermaid syntax error:

graph TD
  A[Goal](1) --> B(Claim);
  B --> C[(Evidence)];

Neither does it appear to work to attach an annotate class to one of the nodes in the diagram, and then follow the instructions listed here, because although the class assignment works, there is no way to add the actual annotation text without encountering the same issue as above:

graph TD
  A[Goal] --> B(Claim (1));      <---- this extra bracket breaks the diagram like before
  B:::annotate --> C[(Evidence)];      <----- this class assignment works, and attaches an `annotate` class to the HTML element

@AoifeHughes or @kallewesterling: curious to know if you can think of a workaround, or whether it's just not possible due to the way that the various markdown parsers and plugins interact.

If not, then it would be good to know if there's some other way to achieve something similar to annotations, or just have a way to add comments to mermaid diagrams in the documentation.

This page is the one I'm playing around with at the moment, as it would be helpful to have comments alongside the introduction of the core elements:

https://github.com/alan-turing-institute/AssurancePlatform/blob/documentation/site/docs/guidance/core-elements.md

[chrisdburr]

Quick additional comment: I've checked the issues/discussions in the Material for MKDocs repo, and squidfunk is very friendly and responsive if this does end up being an upstream issue. However, I haven't played around with it enough yet to justify raising an issue, and expect that the response will be "this isn't possible".

[kallewesterling]

I don't think this is something that's easily done, as there is likely a separate renderer for the mermaid markup -> HTML that doesn't necessarily get passed through/mixed in with the markdown -> HTML that mkdocs runs. I can see if I have some time to look into this more before our meeting on Thursday, but I am not too hopeful about it. If we want to be able to annotate graphics with tooltips, I think we'd have to go into a much more technical way of rendering the diagrams, and I don't think that's within scope for now. (We chatted briefly in our last meeting about what to use to render the diagrams and settled on mermaid for the ease-of-use and reduction of technical debt, and if we wanted to have tooltips, I think we'd have to go down the d3 route, for instance, which is what mermaid uses in the "backend".)

[kallewesterling]

Hold on - there seems to be a way of building in callbacks through Javascript! See this fiddle here for an example: https://jsfiddle.net/s37cjoau/3/

Here are some related issues of interest:

• https://github.com/quarto-dev/quarto-cli/discussions/1054
• https://github.com/mermaid-js/mermaid/issues/1763
• https://mermaid.js.org/syntax/flowchart.html#interaction

[chrisdburr]

Just to add one additional issue to this. It doesn't seem as though Material for MKDocs (MMK) is using the latest version of mermaid, as the ability to add font styling and word-wrapping is not working properly.

For instance, this is how MMK renders the following code:

graph TD
  A["`The outputs of our system are *explainable*.`"] --> B("`The ML model used is *interpretable*`".);

Whereas, this is how it should get rendered:

Also, not sure how to fix the vertical alignment issue (i.e. blank space above the text). Only thing I have found so far is this blog post announcing the feature: https://www.mermaidchart.com/blog/posts/automatic-text-wrapping-in-flowcharts-is-here

[kallewesterling]

Looks like there has finally been some developments here: https://github.com/squidfunk/mkdocs-material/issues/5758#issuecomment-1792078444

[kallewesterling]

There's a pull request for updating mkdocs-material and bringing the latest mermaid version into it: https://github.com/squidfunk/mkdocs-material/pull/6265.

This seems to address at least the styling issues that you mentioned @chrisdburr. However, the annotations is still a pending problem.

[kallewesterling]

Closed as no longer relevant.