docs: mermaid diagrams don't render

[lewismiddleton]

Expected Behaviour They should render out as per the mkdocs-material documentation.

Actual Behaviour The mermaid diagrams over at https://scality.github.io/runner-manager/development/workflows/ don't render. Instead they show raw code blocks.

[lewismiddleton]

I put two implementations up at #568 and #569, you can choose which you prefer or do some digging of your own.

I'd suggest choosing the mermaid2 plugin implementation in #568 and let poetry manage the dependency. Compared to the hard coded mermaid.js version in the extra_javascript implementation that will probably not get updated.

On the other hand, this comment from a mkdocs-material maintainer seems to suggest you should not use a plugin unless you need 'advanced behaviour'.

[lewismiddleton]

I'll add some resources here that I stumbled upon:

Pymdown Superfences extension - small rabbit hole about mermaid diagrams https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#uml-diagram-example https://facelessuser.github.io/pymdown-extensions/faq/#mermaid-diagrams https://facelessuser.github.io/pymdown-extensions/extras/mermaid/#practical-diagrams-sequence-diagrams

A troubleshooting guide at https://mkdocs-mermaid2.readthedocs.io/en/latest/troubleshooting https://mkdocs-mermaid2.readthedocs.io/en/latest/

[lewismiddleton]

I'll add some context here about a small rabbit hole about <div> vs <pre><code>

In the page build logs for mkdocs in #568, mermaid2 is doing something with the <pre><code> blocks and turning them into <div> suggesting that the mermaid2 project knows something about the incompatibility with fence_code_format.

Here's some logs

vscode ➜ /workspaces/runner-manager (main) $ poetry run mkdocs build --strict
INFO    -  MERMAID2  - Initialization arguments: {}
INFO    -  MERMAID2  - Using javascript library (10.4.0):
              https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /workspaces/runner-manager/site
INFO    -  MERMAID2  - Page 'Workflows': found 2 diagrams (with <pre><code='[language-]mermaid'>), converting to <div>...
INFO    -  MERMAID2  - Page 'Workflows': found 2 diagrams, adding scripts
INFO    -  Documentation built in 0.90 seconds

If you look at the mermaid2 source code, they cite a breaking change in python-markdown as the root cause. There's some discussion about this in the implementing PR. But also this code hasn't been touched in 4 years :/