change: Generate mermaid diagrams at build time?

[pawamoy]

Is your change request related to a problem? Please describe.

Currently, inheritance diagrams are generated as Mermaid divs, which are then rendered on the client-side. They need a bit of javascript in order to set the URLs on the clickable nodes. Sometimes these diagrams take a bit of time to render, leaving the ugly div / code block visible to users for one second or less. Also, such dynamic content is not supported by Material for MkDocs' instant previews, so they do not look good at all when hovering on links.

Describe the solution you'd like

I wonder if it would be possible to generate the SVGs at build time (with a Jinja filter), keeping <autoref> elements where <a> links should appear (in the clickable nodes). This way we show all nodes, and resolvable ones will become clickable automatically when autorefs applies cross-refs. This is all done at build time, and won't require any javascript (custom or mermaid.js) on the client-side, meaning diagrams should then be displayed instantly and correctly in instant previews. CSS should work as previously.

Alternatives

Finding a way to hide diagrams from instant previews.

Additional context

I don't think it's a problem if we move the logic for rendering diagrams into Python code, instead of Jinja templates, since this is not something that we likely want to customize (it's really just Jinja loops to render a Mermaid flowchart). It could still be interesting to document how to override filters, in case users want to customize how the SVG is rendered. The filter can always accept options, too.

---

^{This issue was labeled with the fund label. The following section is automatically added by Polar.}

Boost priority in our backlog through Polar's "issue funding". Issues linked to monthly sponsorships of $50 or more (author, upvoters) are already prioritized, see how we manage our backlog.