carpentries / varnish

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

Incorporate mermaid diagrams #125

Open astroDimitrios opened 9 months ago

astroDimitrios commented 9 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 4 months 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
astroDimitrios commented 3 weeks ago

I forgot to put that you add diagrams in the md like this:

```mermaid
    gitGraph
        accDescr {A git graph showing three commits to the main branch and a new seasonal-forecast branch with one commit branched of the HEAD of main.}
        commit id: '41c775b'
        commit id: 'a489b1f'
        commit id: 'cdb7fa6'
        branch seasonal-forecast
        commit id: '8136c6f Add in a seasonal forecasts file'
```

I have bumped the version of Mermaid and updated the CSS as there is something wrong with the figcaption css. This lets the svgs take the full width of the space available.

I have also made overflow scrolling optional so if you have a large diagram you should enable overflow scrolling by adding in the %% overflow comment in your diagram:

```mermaid
    gitGraph
        %% overflow
        accDescr {A git graph showing three commits to the main branch and a new seasonal-forecast branch with one commit branched of the HEAD of main.}
        commit id: '41c775b'
        commit id: 'a489b1f'
        commit id: 'cdb7fa6'
        branch seasonal-forecast
        commit id: '8136c6f Add in a seasonal forecasts file'
```