Support mermaid diagram generation

[di]

Github has announced support for diagram generation via https://github.com/mermaid-js/mermaid: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

Given how many users use the same README for both PyPI and GitHub, we should explore how we could support this.

Here's the relevant parts for how GitHub does it:

When we encounter code blocks marked as mermaid, we generate an iframe that takes the raw Mermaid syntax and passes it to Mermaid.js, turning that code into a diagram in your local browser.

We achieve this through a two-stage process—GitHub’s HTML pipeline and Viewscreen, our internal file rendering service.

First, we add a filter to the HTML pipeline that looks for raw pre tags with the mermaid language designation and substitutes it with a template that works progressively, such that clients requesting content with embedded Mermaid in a non-JavaScript environment (such as a screen reader or an API request) will see the original Markdown code.

Next, assuming the content is viewed in a JavaScript-enabled environment, we inject an iframe into the page, pointing the src attribute to the Viewscreen service. This has several advantages:

It offloads the library to an external service, keeping the JavaScript payload we need to serve from Rails smaller.
Rendering the charts asynchronously helps eliminate the overhead of potentially rendering several charts before sending the compiled ERB view to the client.
User-supplied content is locked away in an iframe, where it has less potential to cause mischief on the GitHub page that the chart is loaded into.

[ekneg54]

would be very nice, because gitlab renders mermaid too

[miketheman]

Relevant, possibly use sandbox mode to begin with on the UI rendering side. https://github.com/mermaid-js/mermaid/blob/4b78a2106d72f0a1a0c03acc71bfdfdd8795db3b/docs/usage.md#enabling-click-event-and-tags-in-nodes

[AdrianDsg]

Rendering multiline code blocks with language tag mermaid to a pre tag in html and adding the JavaScript given in this example taken from python-markdown2 should work.
If both are wrapped in a iframe it might be more secure when serving the mermaid.js library from an external CDN (e.g. jsdelivr). However the library probably would be requested several times when using more than one mermaid diagram.
As mathjax is currently served by the same CDN it might not be an issue.