Description
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.