Adding Mermaid diagram support

[davepagurek]

In one of our contributor docs, we have a diagram rendered with Mermaid since GitHub is able to render those in its readmes. A writer currently working on the documentation for functions like applyMatrix also was wondering if we could use something like GitHub readme inline math in documentation.

We don't necessarily need to implement any of these right away, but do you have a sense of what it would take to integrate them in the future?

[stalgiag]

The former would likely require a plugin, ideally one that supports server-side rendering (to reduce package size). I don't know how different pintora is from mermaid but I see this pintora plugin for Astro.

The latter would just require specific styles.

[ksen0]

Opening this issue for work, but please note that it is currently reserved for http://codeday.org/ - I will update this comment if it becomes open for volunteer contributions again! Thank you for understanding.

The goal is to enable mermaid diagrams to be rendered on the p5.js website.

For example, as Dave mentioned above, there is an architecture diagram in the WebGL contributor docs - but in the matching guide on the website (scroll to classes), it is not rendered. Additional contributor documentation is coming soon that will really benefit from being able to include mermaid diagrams that can be shown both in GH, and on the website. (The https://p5js.org/contribute/ section on the website is built based on https://github.com/processing/p5.js-website/blob/main/src/content/contributor-docs when a new version of p5.js is released.)

It seems that both client-side and build-time options are possible, and it seems that the build-time option (generating the SVGs prior to deployment) may be better, however if the contributor on this tasks finds another recommendation, it can be considered.

The PR should target the main branch of the p5.js-website repository, but after merge should also be cherry-picked into 2.0.

[jai-serr-ace]

Hello, I am Jaime from the CodeDay micro internship opportunity, and I wanted to let you know that me and my group, Octavio, Hien, Eugene, will be working on this issue. Secondly, based on my current knowledge, the issue is about making the section of classes, specifically the code like section that has
classDiagram class Base["p5.Renderer"] { } class P2D["p5.Renderer2D"] { } class WebGL["p5.RendererGL"] { } class Geometry["p5.Geometry"] { }
and so on, look like the example in this link. Basically, making it look like a mermaid diagram; or fix whatever is preventing this part of the page to render as in the preview?
Please let me know whatever I could be misunderstanding about it.

[ksen0]

Hello @jai-serr-ace and team! Welcome. I'll assign you.

I'll try to answer your questions below but please don't hesitate to ask for clarification as much as needed:

1. The "classes" section on the site is a good test case here. However the solution should be general: so if there is another diagram to be added on another page, it should still work. During review, I would check this.
2. There has so far been no feature that would make mermaid diagrams render on the website, so this issue is to add this step. There are two ways to add this feature: something that will render client-side when the page is viewed in the browser; or something that will generate the image at build time. Because it's a new feature, you're welcome to suggest which solution you think would be best: a solution that requires the fewest new dependencies, and the fewest code changes to make the feature work, for example.
3. This may be very difficult to test but if at all possible, tests should be added for all new features. If you're not sure where to start on this, please let me know what your thoughts are about (2), and I could help with the test approach. If it's too much work for the micro-internship, it can also be a separate issue.

I hope this helps, please ping anytime, and if @ me I can find this a little bit quicker, sorry for the delay:)

[jai-serr-ace]

@ksen0 hello again. We have found a little more information about the issue. First, at least for the test case, does it involve a modification to the webgl_mode_architecture.mdx file found in src/content/contributor-docs/{depending on language} en/ ? Second, if so, the modification has to be re-usable in other mdx files, correct? Another we wanted to know about, is the possible solutions. Would it be better to use something simple that is very faster "compile / render", and it friendly with the SEO / SSG as an SVG for example where the CSS can have more natural control over it (Mermaid component or Built time plug in). Or something more interactive and "artistic" as a Depending React diagram component, that could take longer to run and have a little more complication in general?

Edit:
Please let me know whatever I am not understanding or if the questions do not make sense?

[ksen0]

Hi @jai-serr-ace , sorry for the delay in my response!

1. The webgl_mode_architecture.mdx in the p5.js-website repository (src/content/contributor-docs/{depending on language} en/) is generated based on the source .md in p5.js. This is an auto-generated file, created as part of the p5.js release process and ideally would not need modification. However, if it is impossible to support mermaid diagrams on the website without modifying this, then please prepare the PR to show exactly what change is needed in the .mdx file, so then we can update the build script that creates the contributor docs.

2. You could potentially propose any build-time script that uses the .mdx files as they are and creates some modified version which is usable. For example: during routine p5.js-website build, replacing mermaid code with SVG image. So that if there are already images, nothing happens; if there is mermaid diagram, then new image is made. Then, when there are releases of p5.js, all images are updated as part of the website build. So in this example, you could propose something that modifies the .mdx files directly, but still works with the generated contributor-docs .mdx files in their current format. There may be better ways to do this, that was just an example approach.

3. "the modification has to be re-usable in other mdx files, correct?" -- yes, the goal is for any mermaid diagram in the contributor docs should be visible on the site. (The simple diagrams are enough! The GitHub viewer supports lots of different additional diagrams, but this isn't necessary here, especially if it increases complexity.")

4. Simpler is the better start! An interactive/artistic approach may be great in the future, but for now it's important to show the diagrams on the site.

I'll monitor the notifications for this thread more closely and reply as soon as I can if you have further questions. You're welcome to share specific code examples or ideas if you'd like feedback on anything.

[jai-serr-ace]

Hello @ksen0, I wanted to let know you that one of my groupmates fix the mermaid part of it the issue and did as shown in in the preview and it works fine, but we found a bug that comes with the mermaid running from Astro in build time and that is that the CSS is having issues overwritten it into dark mode. This is how it runs

and based on the preview this how is supposed to run like these (I tested it using GitHub appearance and switch in between light mode and dark mode)

The diagram follows the same style as the rest of website, however it does not do it the way Astro can do it which is the version from the preview. It does not look bad, but it makes details as the arrows and small numbers invisible. I was able to make the diagram in dark mode,

however the main issue comes when trying to switch between the modes using the dark mode button from Accessibility. I was wondering if you have any suggestion for this, or is it okay to make a PR with minor issue.

[jai-serr-ace]

Hello, @ksen0. I wanted to let you know that we have found a solution for this particular problem. We created two diagrams (one for light mode and for dark mode) and with some CSS and html scripts made the dark mermaid diagram disappear during light mode and vice versa. In summary, you don't have to worry about it anymore.

[ksen0]

Thanks for the update @jai-serr-ace , great to hear!