[TechDocs] - Support Mermaid Diagrams Using the Addon Framework

Expected Behavior

Expecting techdocs/backstage to render custom JS / mermaid plugin.

Current Behavior

mkdocs/techdocs is not rendering custom JS / mermaid plugin; instead only the raw instructions are presented

Context

I’m running a custom tech-docs backend with the mermaid extension installed in the local container. For example:

Tech-docs custom container:

...
pip install --quiet \
    mkdocs==1.1.2 \
    cookiecutter==1.7.2 \
    Markdown==3.2.2 \
    pygments==2.6.1 \
    mkdocs-material \
    mkdocs-jupyter \
    mkdocs-mermaid2-plugin \
   ...

Your Environment

mkdocs-techdocs-core 0.0.13 mkdocs-plugin-mermaid 0.1.1

My mkdocs.yml config:

plugins:
  - techdocs-core
  - mermaid2

extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
  - https://unpkg.com/mermaid/dist/mermaid.min.js

[OrkoHunter]

We’ll look more into the MkDocs mermaid2 plugin more to see how we can make it work with TechDocs.

But TechDocs loading an external Javascript from its storage and executing it, will be a security threat for a Backstage app. Hence, TechDocs is only allowed to import HTML and CSS.

One possible approach would be to make the files under extra_javascript available in Backstage/TechDocs frontend; and then when the mermaid diagram’s HTML is rendered, it would work as expected. But I’m not too sure.

[kuangp]

Still interested