Teil unserer Arbeit als Entwickler:innen ist es, die Konzepte unserer Software, die wir schreiben, und unsere Gedankengänge anderen zu präsentieren. Um dies präzise und einfach verständlich darzustellen, hilft uns Visualisierung.

Dafür gibt es ein breites Spektrum diverser Tools mit verschiedenen Ansätzen:

Am einen Ende des Spektrums befinden sich grafische Applikation, wie Microsoft PowerPoint oder Google Slides, die mittels Point-and-Click das Erstellen von Diagrammen ermöglichen.

Diese Tools haben den Vorteil, dass sie leicht verständlich sind und keinen Setup-Aufwand benötigen. Bei einfachen Grafiken ist dies ausreichend. Sobald aber die Komplexität der darzustellenden Informationen steigt, sind diese schwer zu pflegen. Man stelle sich z.B. einen Graphen mit mehreren Zuständen vor und will nun einen weiteren einfügen, der mit allen anderen zusammenhängt - das Anpassen aller bisherigen Elemente des Graphen benötigt dabei schnell viel Zeit, die man sich gerne sparen würde.

Am anderen Ende des Spektrums befinden sich Tools, die Grafiken anhand von Programminstruktionen generieren, so wie das Grafikpaket TikZ, das durch das Textsatzsystem TeX interpretiert wird. TikZ ist ein rekursives Akronym für TikZ ist kein Zeichenprogramm, dementsprechend wird auf eine GUI verzichtet und stattdessen Markdown-Text in Vektorgrafiken übersetzt. TikZ selbst kann weitere Pakete einbinden, was für einen hohen Funktionsumfang sorgt.

Die untenstehende Abbildung zeigt die TikZ-Grafik, die auf der Titelseite des Handbuchs zu finden ist, mit dem zugehörigem Code:

1\documentclass{article}
2\usepackage{tikz}
3\usetikzlibrary{snakes,trees}
4
5\begin{document}
6
7\tikzstyle{level 1}=[sibling angle=120]
8\tikzstyle{level 2}=[sibling angle=60]
9\tikzstyle{level 3}=[sibling angle=30]
10\tikzstyle{every node}=[fill]
11\tikzstyle{edge from parent}=[snake=expanding waves,segment length=1mm,segment angle=10,draw]
12\tikz [grow cyclic,shape=circle,very thick,level distance=13mm,cap=round]
13	\node {} child [color=\A] foreach \A in {red,green,blue}
14  { node {} child [color=\A!50!\B] foreach \B in {red,green,blue}
15   { node {} child [color=\A!50!\B!50!\C] foreach \C in {black,gray,white}
16    { node {} }
17   }
18  };
19\end{document}

Wir sehen, dass TikZ es ermöglicht, einen komplexen Graphen mit einer komplexen Syntax zu erstellen. Diese Mächtigkeit von TikZ ist dann von Vorteil, wenn wir facettenreiche Vektorgrafiken erstellen wollen, die genau nach unseren Vorstellungen konfiguriert werden können (um einen Eindruck zu bekommen, was mittels TikZ alles möglich ist, kann man sich gerne diesen tex.stackexchange-Thread anschauen). Der Aufwand zur Installation von TikZ und die hohe Lernkurve sind für einfache Anwendungsfälle allerdings nicht geeignet.

Zwischen der Komplexität von Powerpoint und TikZ ist Mermaid.js angesiedelt. 2014 ins Leben gerufen, hat es mittlerweile eine aktive Community von über 300 Mitwirkenden auf GitHub und gewann 2019 die Auszeichnung "The most exciting use of technology" bei den JS Open Source Awards.

Es spezialisiert sich auf Diagramme, die in der Softwareentwicklung Anwendung finden. Wie TikZ kompiliert es Markdown in Grafiken und bleibt in komplexen Fällen wartbar. Die Syntax von Mermaid.js ist aber deutlich einfacher und die Installation ist in wenigen Schritten möglich. Zudem können seit Februar 2022 Mermaid.js Grafiken auf GitHub gerendert werden.

Wie verwende ich Mermaid.js?

Um Grafiken mit Mermaid.js zu erstellen, gibt es mehrere Möglichkeiten. Es kann als Node-Modul direkt in ein JavaScript-Projekt eingebunden werden. Das geht bei einer React-App in nur drei Schritten:

1yarn create react-app my-mermaid-app
2cd my-mermaid-app
3yarn add mermaid

Im Anschluss können wir eine Grafik in HTML-Code einbinden:

1import mermaid from 'mermaid';
2import './App.css';
3import { useEffect } from 'react';
4
5function App() {
6  useEffect(() => {
7    mermaid.initialize({ startOnLoad: true, theme: 'base' })
8  })
9
10  return (
11    <div className='mermaid'>
12      {
13        `
14        	Hier kommt der Diagramm-Code
15        `
16      }
17    </div>
18  )
19}
20
21export default App;

Benötigen wir nur die Bilder an sich ohne direkte Einbindung in ein Programm, können wir einen Online-Editor wie mermaid.live verwenden, oder wir erstellen uns eine .md-Datei in GitHub und verwenden das Tag

1```mermaid
2   Hier kommt der Diagramm-Code
3```

Ein Diagramm erstellen

Die Syntax für die Diagramme ist einfach gehalten: Ein Mermaid.js Graph besteht zuerst aus einer Titelzeile, die den Typ des Diagramms und dessen Konfiguration festlegen. Darauf folgen Zeile für Zeile Instruktionen, die uns das Diagramm bauen.

Schauen wir uns das am Beispiel eines Git-Graphen an:

1 gitGraph
2   commit id: "C1"
3   commit id: "C2"
4   branch feature
5   commit id: "F1"
6   commit id: "F2"
7   checkout main
8   commit id: "C3"
9   commit id: "C4"
10   merge feature

Das generiert dieses Diagramm:

Der Typ des Diagramms wird in der ersten Zeile durch gitGraph angegeben. Die einzelnen Commits erstellen wir, wie bei Git auch, durch den Befehl commit. Mit id: “C1” beschriften wir den Commit. Commits landen auf dem main-Branch, außer wir zweigen davon auf den feature-Branch ab. Weitere Commits landen auf dem feature-Branch, bis wir mit checkout main wieder auf den Ursprungs-Branch gelangen. Mit merge feature führen wir den feature-Branch zum main-Branch mit einem Merge-Commit zurück.

Anhand des obigen Beispiels wird die Stärke von Mermaid.js deutlich. Der Git-Graph wird erstellt, indem wir die gleichen Befehle wie in der Git-Kommandozeile ausführen. Somit ist es für jeden, der sich mit Git auskennt, auf Anhieb verständlich. Ähnlich verhält es sich mit den anderen Diagrammtypen, die Mermaid.js anbietet. Die Markdown-Syntax entspricht dem Aufbau des Diagramms und ist so kurz wie möglich gehalten. Eine Auflistung aller verschiedenen Diagramme ist auf mermaid-js.github.io zu finden.

Mermaid.js ist ein Visualisierungstool, das durch seine Einfachheit überzeugt. Zwar ist die Anzahl an Diagrammtypen und deren Konfigurierbarkeit eher gering, für den Bereich der Softwareentwicklung sind diese aber oft ausreichend. Zudem sorgen die aktive Community und die Möglichkeit, dass wir Diagramme auf der GitHub-Webseite anzeigen können, dafür, dass Mermaid.js auch in der Zukunft relevant bleiben wird.