Add Mermaid 🧜‍♀️ to Markdown parser

[heremansgeert]

When writing a description for an exercise, it would be great if we could include flowcharts generated by a Markdown'ish syntax.

Currently, I'm working with Visio and exporting it to images. By including the flowcharts in the markdown I can keep all information about an excersies centraly at one location in the repo.

Mermaid is a Javascript library lets you create diagrams and visualizations using text and code¹.

Footnotes

1. Mermaid ↩

[pdawyndt]

Include diagrams in your Markdown files with Mermaid

```mermaid
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
```

  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;

Loading

[bmesuere]

We are dependant on our markdown parser for this. Currently, kramdown has no support for mermaid. It seems like the gitlab fork supports it, but other things might break. For example, math support is lacking there.

[38tter]

Hi @heremansgeert
If you can use kramdown on your environment, probably kramdown-mermaid would help you.

[jorg-vr]

@heremansgeert We have a pr to introduce this, but this introduces quite a lot new javascript dependencies, which also means a lot of maintenance in the future.

Could you give us an indication of how important this feature is to you, so we can make a better decision on whether we want to roll it out?

@BTWS2, @RobbeW, @deepeebee do any of you have an opinion on this? As you are some of our larger content creators, it would be good to know if you would be using mermaid when it is available in Dodona.

[BTWS2]

It seems nice to have, but I don't have that many use cases for it. Exporting to an image and adding it in Markdown doesn't seem such a hassle to me. A flow chart doesn't change that often I think, so adding the Mermaid code to the existing GitHub repo and exporting to an image seems fine to me. If you export to an image you have more control of the exact lay-out I think, but I don't have experience with Mermaid.

[RobbeW]

Hi,
I don't have any experience with Mermaid. If I would need to design a flowchart for an exercise, this is mostly done in class or during a lecture on the blackboard. I view this to be part of the preliminary steps in writing code (decomposition, identifying variables, sketching your flow) and something I would present to my students in the body of the exercise.
(I can only comment on how I use Dodona in my particular setting, in class, without independent or work-from-home-students.)

If my opinion would change, I feel capable to export to an image and include that in the markdown. So I agree with the 'nice to have but not of increased relevance for me'. I'll check with my colleague for his opinion on the matter.

[heremansgeert]

@jorg-vr Thanks for taking a look at this. But I consider this nice to have but not crucial. Introducing a lot of dependencies just for this feature is probably not worth the effort.

As @RobbeW mentioned, I primarily used flowcharts for the first exercises and don't add them to my descriptions later on.

Regarding the feedback about uploading an image, since this is only a small effort:

This is of course true. Uploading an image and including it in the description is only a small effort. However... I like to include as much information in my exercise repositories in markdown syntax. I prefer to generate resources from the markdown if at all possible.

I include a file called feedback.md in my evaluation directory. In there I store the feedback I give to students when they take a test (I've been using Dodona before stored feedback was available). Although I love the new feature to store the feedback, personally, I would love that this could be pulled from the repository. So when I re-use an exercise next year, the feedback is already available. The same can be said about evaluation (scores).

I am now starting with an HTML course after giving Docusaurus a try. One of the features I liked in Docusaurus is that you can use a Browserwindow component. It allows rendering HTML for markdown.

For example, this code:

<BrowserWindow>
<Tabs>
  <TabItem value="De A-tag" label="De a-tag" default>
  <p>
    Waarvoor kan je het <a href="https://www.w3schools.com/tags/tag_a.asp">HTML</a> element gebruiken?
    </p>
    <ul>
        <li>Links naar andere webpagina's bv naar de <a href="https://www.sintcordula.be">website van onze school</a></li>
        <li>Links naar andere bestanden bv naar een <a href="opdrachten/Protosterren/artikel-protosterren.txt">txt-bestand</a></li>
        <li>Links naar een e-mailadres bv naar <a href="mailto:[email protected]">het e-mailadres van de school</a></li>
        <li>Links naar een telefoonnummer bv naar <a href="tel:+32 03 658 94 49">het telefoonnummer van de school</a></li>
    </ul>

  </TabItem>
  <TabItem value="Broncode" label="Broncode">
```html
    <p>
    Waarvoor kan je het <a href="https://www.w3schools.com/tags/tag_a.asp">HTML</a> element gebruiken?</p>
    <ul>
        <li>Links naar andere webpagina's bv naar de <a href="https://www.sintcordula.be">website van onze school</a></li>
        <li>Links naar andere bestanden bv naar een <a href="opdrachten/Protosterren/artikel-protosterren.txt">txt-bestand</a></li>
        <li>Links naar een e-mailadres bv naar <a href="mailto:[email protected]">het e-mailadres van de school</a></li>
        <li>Links naar een telefoonnummer bv naar <a href="tel:+32 03 658 94 49">het telefoonnummer van de school</a></li>
    </ul>

```

Would be rendered like this:

One can say it's easy to take a screenshot from the rendered HTML code, but I hope you'll see that there is a benefit from generating this from the Markdown.

[jorg-vr]

Thanks everyone for the responses. Based on your feedback, we'll close this issue and the related pr as a won't fix.

@heremansgeert I'll respond to your other notes

I include a file called feedback.md in my evaluation directory. In there I store the feedback I give to students when they take a test (I've been using Dodona before stored feedback was available). Although I love the new feature to store the feedback, personally, I would love that this could be pulled from the repository.

Being able to reuse feedback across courses and exercises is on our radar. See #4993
I don't think storing the feedback in the repository will be the preferred solution, as we have a lot of users who use the feature, but don't create their own exercises. But the final implementation still has to worked out in detail.

The same can be said about evaluation (scores).

I'll take this into account when working on #4940
Reusing test and exams, and thus reusing score distributions was not yet on our radar, but it is a relevant usecase.

One of the features I liked in Docusaurus is that you can use a Browserwindow component. It allows rendering HTML for markdown.

We already support this, without the need for the <BrowserWindow> tag. You can simply use HTML within your markdown files, and it will render as plain HTML. An example in our documentation about the spoiler tag also explains how you can keep using markdown within a HTML element.

[BTWS2]

@heremansgeert I would advise against using an HTML-render to show the desired result for an HTML-exercise. This way the solution is only two clicks away (Rightclick, Inspect or View page source). I use images for the render for this reason (and consistent lay-out).

[heremansgeert]

@BTWS2 That is unfortunately true for exercises but could come in handy for reading activities. Again, scope is limited.