Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Incorporate mermaid diagrams #125

Open
wants to merge 22 commits into
base: main
Choose a base branch
from
Open

Incorporate mermaid diagrams #125

wants to merge 22 commits into from

Conversation

astroDimitrios
Copy link
Contributor

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 astroDimitrios mentioned this pull request Feb 21, 2024
Merged
@astroDimitrios astroDimitrios mentioned this pull request Feb 28, 2024
Merged
@ns-rse ns-rse mentioned this pull request Mar 26, 2024
Merged
@astroDimitrios
Copy link
Contributor Author

astroDimitrios commented Aug 1, 2024 •
edited
Loading

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 astroDimitrios mentioned this pull request Aug 2, 2024
Open
@Bisaloo Bisaloo mentioned this pull request Aug 8, 2024
Open
@astroDimitrios
Copy link
Contributor Author

astroDimitrios commented Nov 7, 2024 •
edited
Loading

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'
```

@astroDimitrios
Copy link
Contributor Author

I have been using my version of Varnish with Mermaid diagrams in semi-anger for a while, there are some limits that I think I can fix:

  • Mermaid diagrams can't be used in Tabs or Spoilers, this is because they are only rendered if the element is visible when the page is loaded. I can probably fix this by adding in JS to reload Mermaid on tab switching. Might be more difficult for spoiler blocks. I'm not sure how limiting this will be for others.
  • They aren't rendered in the all in one page. This I think is generated in R so I might need pointing to where this happens so I can also keep Mermaid diagrams.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[Future] Incorporate mermaid diagrams
1 participant
@astroDimitrios