Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support mermaid diagram generation #223

Open
di opened this issue Feb 14, 2022 · 3 comments
Open

Support mermaid diagram generation #223

di opened this issue Feb 14, 2022 · 3 comments

Comments

@di
Copy link
Member

di commented Feb 14, 2022

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
Copy link

ekneg54 commented Jun 21, 2022

would be very nice, because gitlab renders mermaid too

@miketheman
Copy link
Member

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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants