[Future] Incorporate mermaid diagrams

zkamvar commented 2 years ago

This is something @tobyhodges will be happy about.

When GitHub announced its support for mermaid diagrams in issue comments, this seemed too good to be true. When I read the documentation, it seemed like we would need to host it on our own server in order to render it in a way that makes sense.

BUT the good people at CSSTricks wrote up a good article on how to include mermaid in static sites it turns out that it's a lot like MathJax where it will render when available, but give a sensible fallback if not. Neat!

Here's an example of what we could to to incorporate concept maps into our infrastructure:

Source:

graph TD;
    M[mental model];
    E[edges];
    N[nodes];
    CM[Concept Map];
    R[relationships];
    C[concepts];
    CM --depict-->  M;
    CM --contain--> N;
    CM --contain--> E;
    E  --connect--> N;

    E  --describe--> R;
    R  --between--> C;
    N  --describe----> C;

Output:

graph TD;
    M[mental model];
    E[edges];
    N[nodes];
    CM[Concept Map];
    R[relationships];
    C[concepts];
    CM --depict-->  M;
    CM --contain--> N;
    CM --contain--> E;
    E  --connect--> N;

    E  --describe--> R;
    R  --between--> C;
    N  --describe----> C;

Now the drawbacks to this are that people are going to have to learn this diagramming language, but the benefit is that there are several places to test it out without having to re-render the site over and over.

tobyhodges commented 2 years ago

🎉

I am inclined to offer this as one of a few ways for people to include concept maps in their lesson, alongside "take a photo of your hand-drawn map" and "embed an image you've made elsewhere". It will be an excellent tool for those lesson developers comfortable enough with learning the syntax.

ns-rse commented 7 months ago

It would be great to have the ability to incorporate Mermaid Diagrams in Carpentry material as not only do they allow Concept Maps but you can also include Git diagrams.

Source

```mermaid
%%{init: {'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}
         }
}%%
    gitGraph
       commit id: "Last feature"
       commit id: "v0.1.0"
       branch "v0.1 fixes"
       commit "This branch is for fixes to v0.1"
       branch "Missing JSON files for v0.1"
       commit id: "Add missing JSON to v0.1.0 branch"
       checkout "v0.1 fixes"
       merge "Missing JSON files for v0.1"
       commit id: "v0.1.1"
       checkout main
       commit id: "Feature1 for v0.2.0"
       commit id: "Feature2 for v0.2.0"
       commit id: "v0.2.0"
       branch "v0.2 fixes"
       commit id: "This branch is for fixes to v0.2"
       branch "Missing JSON files for v0.2"
       commit id: "Add missing JSON to v0.2.0 branch"
       checkout "v0.2 fixes"
       merge "Missing JSON files for v0.2"
       branch "More changes for v0.2"
       commit id: "Update Cadenza logo"
       commit id: "Update README"
       checkout "v0.2 fixes"
       merge "More changes for v0.2"
       commit id: "v0.2.1"
       checkout main
       commit id: "Cadenza Baseline"
       commit id: "Unit Tests for evaluators"
       commit id: "Unit Tests for enhancers"
       commit id: "v0.3.0"
       branch "v0.3 fixes"
       commit id: "This branch is for fixes to v0.3"
       branch "Fixing something in the future on v0.3"
       commit id: "Fix something in the future"
       checkout "v0.3 fixes"
       merge "Fixing something in the future on v0.3"
       checkout "v0.2 fixes"
       branch "Fixing something in the future on v0.2"
       commit id: "Fix the same problem on v0.2 branch"
       checkout "v0.2 fixes"
       merge "Fixing something in the future on v0.2"
       commit id: "v0.2.2"
       checkout "v0.3 fixes"
       commit id: "v0.3.1"
       checkout main
       commit id: "Refactor HAAQI"
       commit id: "Refactor HASQI"
       commit id: "Refactor HASPI"
       commit id: "v0.4.0"
       branch "v0.4 fixes"
       commit id: "This branch is for fixes to v0.4"
       checkout "main"
       commit id: "First of many new features"
       checkout "v0.4 fixes"
       branch "Fix something in v0.4"
       commit id: "Fix problem 1 on v0.4"
       commit id: "Fix problem 2 on v0.4"
       checkout "v0.4 fixes"
       merge "Fix something in v0.4"
       commit id: "v0.4.1"
       checkout main
       commit id: "Lots more enhancements"


**Output**

```mermaid
%%{init: {'theme': 'base', 'gitGraph': {'rotateCommitLabel': true}
         }
}%%
    gitGraph
       commit id: "Last feature"
       commit id: "v0.1.0"
       branch "v0.1 fixes"
       commit "This branch is for fixes to v0.1"
       branch "Missing JSON files for v0.1"
       commit id: "Add missing JSON to v0.1.0 branch"
       checkout "v0.1 fixes"
       merge "Missing JSON files for v0.1"
       commit id: "v0.1.1"
       checkout main
       commit id: "Feature1 for v0.2.0"
       commit id: "Feature2 for v0.2.0"
       commit id: "v0.2.0"
       branch "v0.2 fixes"
       commit id: "This branch is for fixes to v0.2"
       branch "Missing JSON files for v0.2"
       commit id: "Add missing JSON to v0.2.0 branch"
       checkout "v0.2 fixes"
       merge "Missing JSON files for v0.2"
       branch "More changes for v0.2"
       commit id: "Update Cadenza logo"
       commit id: "Update README"
       checkout "v0.2 fixes"
       merge "More changes for v0.2"
       commit id: "v0.2.1"
       checkout main
       commit id: "Cadenza Baseline"
       commit id: "Unit Tests for evaluators"
       commit id: "Unit Tests for enhancers"
       commit id: "v0.3.0"
       branch "v0.3 fixes"
       commit id: "This branch is for fixes to v0.3"
       branch "Fixing something in the future on v0.3"
       commit id: "Fix something in the future"
       checkout "v0.3 fixes"
       merge "Fixing something in the future on v0.3"
       checkout "v0.2 fixes"
       branch "Fixing something in the future on v0.2"
       commit id: "Fix the same problem on v0.2 branch"
       checkout "v0.2 fixes"
       merge "Fixing something in the future on v0.2"
       commit id: "v0.2.2"
       checkout "v0.3 fixes"
       commit id: "v0.3.1"
       checkout main
       commit id: "Refactor HAAQI"
       commit id: "Refactor HASQI"
       commit id: "Refactor HASPI"
       commit id: "v0.4.0"
       branch "v0.4 fixes"
       commit id: "This branch is for fixes to v0.4"
       checkout "main"
       commit id: "First of many new features"
       checkout "v0.4 fixes"
       branch "Fix something in v0.4"
       commit id: "Fix problem 1 on v0.4"
       commit id: "Fix problem 2 on v0.4"
       checkout "v0.4 fixes"
       merge "Fix something in v0.4"
       commit id: "v0.4.1"
       checkout main
       commit id: "Lots more enhancements"

carpentries / varnish

[Future] Incorporate mermaid diagrams #34