Whitelist something that lets Jekyll render ```mermaidJS by default so the same markdown renders the same mermaidJS image

[duaneking]

I'm in good faith tracking this as a CRITICAL ACCESSABILITY ISSUE for people in the development community who are visually disabled and use mermaidjs to communicate visual ideas and want to use Github Pages.

Worse, GH stated they supported this in a big blog post, and they clearly don't, because I cant copy a mermaidJS markdown file and have it show up on GitHub Pages using only the default GHPages flow. If this is the wrong place, let me know and I will simply refile this bug as needed to assist in good faith.

This fix needs to be on the GitHub side to mitigate duplicated effort and to support the best accessibility

This issue affects

• Everybody on github using GitHub Pages who read https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/
• The blind/disabled development community who wants to use the "standard" mermaid support on GitHub on GitHub Pages to communicate visual ideas.

Issues

• The site generated by GitHub Pages does not render mermaidJS by default, despite the fact that GH has publicly and falsely declared that its supported across the entire website for all markdown files per https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ when that is clearly not the case.
• The jekyll rendering pipeline used by GH pages actively blocks all non-whitelisted plugins from being loaded.
• The jekyll rendering pipeline used by GH pages does not include a plugin in the whitelist that can be used to render mermaidJS.
• The jekyll rendering pipeline used by GH Pages also corrupts/mis-renders standard GitHub "```mermaidjs" markdown into "mermaid-language" code html blocks
• If Github Pages is about ease of use, and if the expectation is that the markdown rendering of GitHub should work on GitHub Pages, that's not happening.

What did you do (e.g., steps to reproduce)

Tried to use standard github markdown with the ```mermaid tag as described on https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

What did you expect to happen?

I expected it to render mermaid with no other work from me.

What happened instead?

MermaidJS is not rendered at all and the Jykll system is also parsing it wrong and rendering the wrong thing.

Additional information

https://rabestro.github.io/test-mermaid/ and https://github.com/rabestro/test-mermaid shows the issue perfectly

Additional Repos showing this problem:

I also am seeing this on my own github.io

[yoannchaudet]

Hello @duaneking and thank you for opening this issue.

The third-party plugin Jekyll seems to recommend for rendering MermaidJS diagrams is https://github.com/jasonbellamy/jekyll-mermaid but that would not do what you are after since it relies on Liquid syntax to render such diagrams (which is the Jekyll way too).

We support two markdown processors in our default Jekyll build pipeline:

• kramdown (which is the default)
• GitHub Flavored Markdown (GFM)

Kramdown can be extended with custom syntax highlighter. I have not found one that we could just whitelist so we will need to write one.

GFM could I think be extended right here.

Mermaid diagrams are rendered in a security sandbox for github.com so it's not something that can be re-used "for free". Also since accessibility is one concern we will likely want to think about a way to display a graph in "full screen" and probably make sure the diagrams render fine with most default themes we support.

Open for suggestions/contributions.

Open to whitelisting https://github.com/jasonbellamy/jekyll-mermaid to get a quicker solution available. I also agree that supporting MermaidJS rendering directly in markdown codeblocks would be nicer.

[duaneking]

Are you saying that this is a bug in the github flavored markdown renderer?

Because github flavored markdown should include full mermaid rendering by default if GitHub has publicly stated that it is supported, and they have.

I filed a bug to that effect with customer support and it was ignored for a week and then closed with extreme malice. I'm not sure what to do because github themselves doesn't seem to care about accessibility or support of the thing that they publicly claim that they support.

[yoannchaudet]

First I am sorry that you did not have a good experience with support. I can assure you they are not being malicious in any way and on the opposite, striving to support everyone. I would have potentially missed your messages without them.

I already clarified that the announcement you are referring to did no cover GitHub Pages.

GFM is not a renderer per say, it is a specification and it does not specify how code blocks are to be rendered.

Mermaid is rendered on the client side with the help of JavaScript. A renderer not only need to output the right HTML it needs to properly include the library (i.e. distribute it), configure it and initialize it. Ideally in a lazy way (we would not want to include and initialize Mermaid in over 17M Pages sites if they don't need it). When you are github.com and share one HTTP origin with millions of users you have further security concerns which is the reason the way GitHub renders markdown into HTML is very specific and not "shareable" (and that I am unable to find any other renderer doing Mermaid out of the box).

To get back to your point, supporting Mermaid rendering on GitHub Pages is probably not a one-line change and I already laid out some solutions in my previous message.

If you know a plugin that can do such thing by all means share it here and we will be happy to see how we can integrate it.

At the risk of repeating myself, I am not here to argue but to help. I get your point and agree there is value in being able to render Mermaid diagrams straight from markdown in Pages.

I'll surface this issue to my team.

[duaneking]

With respect, even using the plugin that support told me to use defeats the entire purpose of what I am asking for, and does not solve my use case.

Support said to use https://github.com/jeffreytse/jekyll-spaceship and do it all manually; but that defeats the use case because that plugin is broken by design and requires a different mermaid tag syntax that requires all .md files be effectively customized to only render using that plugin, and do not want to have to use custom syntax or do extra work or use multiple different files to meet the different expected mermaidjs formats expected from these different approaches over GitHub pages simply using the exact same format as github proper and depending on the "standard" mermaidJS support.

The same mermaidJS file should render in a reliable and consistent way, on github.com or on gh-pages, without any file changes. I should be able to clone a repo with .md files in it that renders well in mermaidJS on normal github, and be able to deploy that using the default github pages flow and have it look effectively the same on github pages.

[piranna]

The same mermaidJS file should render in a reliable and consistent way, on github.com or on gh-pages, without any file changes. I should be able to clone a repo with .md files in it that renders well in mermaidJS on normal github, and be able to deploy that using the default github pages flow and have it look effectively the same on github pages.

I think this is the point, if It renders on GitHub.com, It should do It too in GitHub.io, since they have the same data source. Is there any advance on this topic? It has been open for two years now, and i was awaiting for It since jekyll-starship doesn't works for me on my personal website, only projects started from Scratch (GitHub Pagés publisher should be refactored as a GitHub Action and replaced the actual pipeline for a GitHub Actions one, to be able to reuse and have a better integration, but that's another story)...

There's no need to do rendering on client side, It can be done on server side when building the site, having original Mermaid code as a fallback if image can't be rendered, like BrailleTTY devices or alike.

[emiltin]

Hi,
We would love to be able to use Mermaid diagrams on GitHub Pages. It would be great to be able to use code blocks with the ``` syntax, because you can then reuse/copy diagrams between GitHub comments, Gist, etc and GitHub pages.

We support two markdown processors in our default Jekyll build pipeline:

• kramdown (which is the default)
• GitHub Flavored Markdown (GFM)

Kramdown can be extended with custom syntax highlighter. I have not found one that we could just whitelist so we will need to write one.

GFM could I think be extended right here.

I would like to help out, but don't full understand the above. Is it just matter of making sure the ```syntax get's converted to an HTML class?

[cben]

There's no need to do rendering on client side, It can be done on server side when building the site, having original Mermaid code as a fallback if image can't be rendered, like BrailleTTY devices or alike.

IIUC mermaid relies on browser for layout so all existing "headless" solutions run a full [headless] browser on server...
And multiple "mermaid as blackbox" solutions are wrapped in HTTP server, for flexibility that people can use them as external images.
I guess not best tradeoff across github — e.g. editing/posting a comment should render faster on client than browser-in-a-server — but not insane for Pages build time?

https://github.com/felixvanoost/jekyll-kroki has some nice qualities:

• It supports same ```mermaid syntax GitHub & GitLab already do in markdown! Plus many other types of diagram blocks.
• It uses a server to convert, but at build time; the resulting HTML gets static SVG, no JS needed! Shifting the security concerns from "JS on github domains 😟" to "request to self-contained server 📦" might be more sustainable? Especially if GH hopes to add more renderers in future...
• IMHO, the best thing about [Kroki]((https://kroki.io/) is that it's the closest I've seen to (de-facto) standardized namespace for block types to render. If major sites rely on Kroki, and a new renderer FooJS emerges, we'll avoid silly syntax divergence like ```foojs vs. ```foo vs. ```foo-diag, and markdown will remain inter-operable 🙏.
  GitLab already supports it, as optional extension to markdown, reST, asciidoc, and many other lightweight markup formats — an M*N inter-operability win! (IIUC they leave it user's problem to host or config a server. The public gitlab.com instance apparently has this integration off, it only seems to support mermaid & `plantuml` which were builtin before kroki?)

Would simply adding jekyll-kroki to the allowlist help by itself, or does GitHub also need to take on hosting their own Kroki instance?

• Privacy: sending diagrams to third-party may be a concern?
• See Security section about risks of malicious SVG from untrusted server?
• The server is open-source & self-hostable.
  It's kinda a "distro" around many backends. Some of the backends may be heavy (e.g. "TikZ" converter actually runs full latex process!), but each some come in separate optional containers.

EDIT: if my tone was unclear, I'm just a user, not employee.