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

duaneking commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 4 months ago

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 commented 1 month ago

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?

github / pages-gem