Mermaid Graphen in Jekyll

Als Erweiterung für Markdown Readme Dateien in GitLab kenne ich das Mermaid Plugin schon länger.
Aber aktuell nutze ich es wieder häufiger in Dokumentationen für Ablaufdiagramme.

Hmm … und eigentlich wäre das doch ganz toll für die Homepage und im Blog … aber wie richtet man diese Erweiterung in Jekyll ein?

Was ist Mermaid?

Mit Mermaid definiert man in ASCII Form Abhängigkeiten zwischen Elementen und das Plugin zeichnet dann eine graphische Darstellung daraus. Es ist also eine Erweiterung die so ähnlich wie das Code-Highlighting-Plugin Texte liest und die Darstellung dann farblich “anpasst”.

Am Ende bewirkt dann ein Text-Code wie

graph LR
  A[Home] -- go to -->    B(Here)
  A       -- fly to -->   C(There)
  B       -- drive to --> D[[Destination]]
  C       -- run to -->   D 

die Zeichnung eines Diagramms wie folgt:

Man nutzt IDs (im Beispiel A, B, C, und D) und Zeichenpfeile um sie zu verknüpfen und kann dann mit Klammern eckige und abgerundete Kasten rund um Beschreibungen dazu definieren.
Beim Zeichnen des Graphen versucht Mermaid sein bestes um eine ansprechende Grafik zu erzeugen. Manchmal muss man aber auch die Reihenfolge der Verknüpfungszeilen umstellen, damit von links nach rechts bzw. von oben nach unten alles gut ausbalanciert ist.

Eine gute Übersicht über alle Möglichkeiten findet man natürlich auf der Webseite

Einrichtung in Jekyll

Kurzfassung: Mermaid gibt es als reine JavaScript Implementierung, die man einfach dem eigenen Jekyll Projekt hinzufügt. Installiert man dann noch das Ruby GEM jekyll-mermaid und richtet es in der _config.yml ein, kann man schon loslegen.
Die Jekyll Erweiterung braucht den Pfad zu den Javascript Sourcen, weil einfach ein <script src="path/to/mermaid.js"> Tag eingefügt wird und der Text-Code dem Javascript vorgeworfen wird. Dieses zeichnet dann das Ergebnis in ein dynamisch eingefügtes SVG Element.

Für die Installation braucht man also folgende Schritte:

1. Download der mermaid Sourcen von github.com/mermaid-js
2. Kopieren der Dateien aus dem Unterordner dist_dev ins eigene Jekyll Projekt, z.B.: nach /assets/mermaid
3. Installation des Jekyll mermaid Plugins per gem install jekyll-mermaid

4. In der Datei Gemfile im Jekyll Projekt: Eintrag der Zeile gem "jekyll-mermaid" innerhalb des Blocks group :jekyll_plugins do

   group :jekyll_plugins do
     gem "first-plugin"
     gem "some-plugin"
     gem "other-plugin"
        
       gem "jekyll-mermaid"
   end
   

5. In der Datei _config.yml im Jekyll Projekt: Hinzufügung der YAML Einträge:

   plugins:
     - jekyll-mermaid
   mermaid:
     src: "/path/to/mermaid/mermaid.js"
   

Tja, und nun kann es auch schon losgehen. In Jekyll muss der mermaid Block wie folgt kodiert werden:

 ... some other markdown text
 
 {% mermaid %}
 graph TD
   A[Home] -- go to -->    B(Here)
   A       -- fly to -->   C(There)
   B       -- drive to --> D
   C       -- run to -->   D    
 {% endmermaid %}

some other markdown text ...

Fazit

Echt coole Sache, dieses Plugin. Nun kann ich auch Abläufe im GATE Projekt grafisch anschaulich beschreiben, ohne dass ich immer JPEGs und PNGs dafür einbinden muss.

Eine weitere geniale Erfindung ist der Online-Editor unter:
mermaid-js.github.io/mermaid-live-editor
Mit diesem kann man sofort sehen, wie der eingetippte Code interpretiert und gezeichnet wird. Damit kann man den idealen Graphen entwerfen und dann das Resultat direkt in die finale Markdown Datei kopieren.

Fast Schade, dass ich das erst jetzt entdeckt habe. Schließlich hätte ich dieses Feature vom Anfang an auf opengate.at nutzen können. Aber ein paar Graphen kann ich ja rückwirkend in ältere Seiten einfügen.