carpentries / varnish

Template for pkgdown site
https://carpentries.github.io/varnish/
Other
7 stars 25 forks source link

Incorporate mermaid diagrams #125

Open astroDimitrios opened 6 months ago

astroDimitrios commented 6 months ago

Closes #34

What: Add the ability to render Mermaid diagrams in the Workbench.

Why: See #34 - You can make all sorts of cool diagrams including flowcharts (learner pathways), git diagrams etc.

Based off css-tricks.

Summary

This adds in the Mermaid Javascript code as a dependency for the workbench. I have included it and squashed it with the other javascript as this was faster than importing as a module/script from the web. I have included the recommended setup from the css-tricks link above so it responds to dark mode. I have used the accessible description Mermaid tag, accDescr, to populate a figure caption for the generated SVG. Some examples are shown below from css-tricks and #34. The git diagram is very large - perhaps lesson creators should consider whether to allow such large diagrams - I have limited the max height to 80% of the view height in the css and set the overflow to scroll.

NOTE: The way the new JS populates the figcaption demands that the accDescr be in the multiline format ie:

accDescr {This is correct.}
accDescr {This is correct. 
Multiline correctness.}
accDescr: This is NOT correct.

Examples

A basic chart:

Mermaid-1

and with the Diagram source code toggle expanded:

Mermaid-1-expanded

An example from #34 with a title:

Mermaid-2

The git example from #34 with scroll overflow and title:

Mermaid-3
astroDimitrios commented 1 month ago

Brought up to date with main and the mermaid diagrams now respect your chosen theme:

Dark Mode Mermaid 2 - Light Comparison Dark Mode Mermaid 1