Mermaid

It is time for graphs and pictures to better illustrate the archtitecture of various stuff I am bulding.
So I settled on mermaid, wich is a lightweight markdown-like script language for chart generation.
In this post I am presenting you the way I set it up with Github Pages.

What is mermaid?

Mermaid generates nice graphs out of markdown-like syntax on the client side. So this:

<div class="mermaid">
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</div>

generates this nice looking graph:

Github Pages don’t allow you to install additional plugins to Jekyll, so the mermaid integration has to be “native”.
I stumbled upon this post by Kai Zhang, that nudged me in the right direction.
Combined with the current doc by mermaid, I managed to set up a kind of decent install with my Jekyll instance.

Installation

Download the current mermaid release from the Release Page and extract the JS & CSS files from the dist folder.
I would recommend using mermaid.min.js combined with one of three CSS-files¹. Copy these into the assets folder in your Jekyll instance.
If you don’t have an assets folder right now, simply create it parallel to your _posts folder.

The next step is including these files in your templates.
I chose to define the includes at the end of my post.html layout, as I will only use graphs in my posts.
If you’ve followed along, you can now apped this to your post.html:

<script src="/assets/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
<link rel="stylesheet" href="/assets/mermaid.forest.css">

And that’s it - mermaid should now be working. To add a diagram to your post, simply insert
<div class="mermaid"> DIAGRAM_STUFF </div>
at a location of your liking.