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.

[Mukhsin0508]

Hello Team

Has this been implemented? cuz as far as I see, mermaid isn't working on PyPI UI based on my new library

Any updates on this? I would love to help!)

[miketheman]

Has this been implemented?

This issue is still open and you've seen the behavior not implemented, so not yet.

Any updates on this? I would love to help!)

That's great! As a start, read through the context on this issue and any linked ones to understand what's been explored already, and recommend a path forward.

[AdrianDsg]

@Mukhsin0508 Thanks for looking into this.

@miketheman Please consider commenting on my message above as well. Thanks