Mit Mermaid erstellen Sie Diagramme aus textbasierten Anweisungen und binden sie in die beiden Beschreibungssprachen Markdown und Asciidoc ein.

Möchten Sie Ihre Dokumentation vereinfachen und komplexere Werkzeuge wie Visio, Dia oder Inkscape vermeiden, um Abläufe in Ihrem Programmcode darzustellen und zu erklären, dann könnte Mermaid genau das Richtige für Sie sein.

Bereits in früheren LinuxUser-Ausgaben standen Programme aus dem Paket Graphviz [1] im Mittelpunkt, die ebenfalls aus ASCII-Zeichen hübsche Grafiken [2] und Strukturbäume [3] generieren. Mit derselben Idee betritt nun das auf Javascript basierende Mermaid [4] die Bühne. In derselben Kategorie bewegt sich auch Js-sequence-diagrams [5]. Es fokussiert zwar nur auf UML-Sequenzdiagramme, dafür aber in verschiedenen Ausgabestilen, die unter anderem an handschriftliches Zeichnen erinnern.

Praktischerweise folgt Mermaid dem minimalistischen Konzept vom Markdown und Asciidoc. Das öffnet Türen zum automatisierten Generieren von Dokumenten sowie der Integration in Webseiten. Das federführend vom Skandinavier Knut Sveidqvist entwickelte Tool steht unter MIT-Lizenz, die Entwicklung erfolgt gemeinschaftlich über eine Projektseite auf GitHub [6].

Im Detail

Mermaid steht als eigenständiges Tool für die Kommandozeile [9] und als Javascript-Bibliothek zur Integration in eine Webseite bereit. Mithilfe des Live-Editors [6] auf der Mermaid-Webseite probieren Sie die Funktionen ohne vorherige Installation aus und erfahren so, was die Beschreibungssprache alles ermöglicht. Listing 1 enthält das Ablaufdiagramm, mit dem Abbildung 1 entstand.

graph TD;
A[Umzug] -->|Termin setzen| B(bei Umzugsfirma ein Auto mieten);
B --> C{Umzugskisten packen};
C -->|15 Kisten| D[Wohnzimmer];
C -->|5 Kisten| E[Küche/Bad];
C -->|4 Kisten| F[Schlafzimmer];

Abbildung 1: Zum Erstellen eines schlichten Umzugsdiagramms genügen Mermaid bereits wenige Anweisungen.

Mermaid orientiert sich an Markdown, geht aber noch einen Schritt weiter und überträgt dessen Konzept auf Fluss-, Sequenz- und Gantt-Diagramme. Dabei fällt die Syntax sparsamer aus als bei Graphviz, ohne Kompromisse beim Funktionsumfang einzugehen.

Wie Listing 1 zeigt, beschreiben Sie jedes Element in einem Diagramm mithilfe einfacher Anweisungen. Jede einzelne Zeile der Beschreibung schließen Sie korrekterweise mit einem Semikolon ab, der Interpreter verzeiht hier aber Fehler. Nach der Deklaration des Diagrammtyps folgen die einzelnen Knoten sowie die Kanten, also die Verweise, wie die Knoten miteinander in Bezug stehen und aussehen.

Über zusätzlichen Text sowie Klammern bestimmen Sie die grundsätzliche Darstellung der Knoten und Kanten sowie deren Beschriftung. Mithilfe von Cascading Style Sheets (CSS) geben Sie der Abbildung dann den letzten Schliff; drei Vorlagen liefert die Software bereits mit.

Typen von Diagrammen

Mermaid bietet eine Visualisierung für Graphen oder Bäume, Sequenzen, Gantt- und Klassendiagramme sowie Git-Graphen an. Jedes Diagramm leiten Sie mit einem passenden Schlüsselwort ein, etwa graph, sequenceDiagram oder gantt.

Für einen Graphen geben Sie zusätzlich die Leserichtung an. TD steht für “top down”, TB für “top bottom” (von oben nach unten), BT für “bottom top” (von unten nach oben). RL bedeutet “right left” (von rechts nach links) und LR “left right” (von links nach rechts). Listing 1 beschreibt einen Graphen für einen Umzug, den Sie von oben nach unten lesen und der daher die Angabe TD trägt.

Anhand einiger Beispiele zeigen wir im Folgenden, wie Sie mithilfe von Mermaid die verschiedenen grafischen Darstellungsformen umsetzen. Alle Abbildungen stammen aus dem bereits angesprochenen Live-Editor von der Webseite des Projekts.

Geben Sie dort die Beschreibung im Textfeld links ein, so generiert das Tool daraus in Echtzeit rechts daneben eine entsprechende Abbildung. Um diese später in anderen Dokumenten zu benutzen, laden Sie sie über einen darunter angezeigten Link entweder als Datei im SVG-Format herunter, oder Sie erstellen einen Screenshot (etwa mit Gimp, Shutter oder Hotshots).

Graphen und Bäume

Abbildung 2 zeigt einen Graphen für mögliche Reiserouten über die Autobahn von Magdeburg nach Dresden. Diesen Graphen lesen Sie von links nach rechts (LR). Bei der Formulierung eines Graphen gilt es, einige Dinge zu beachten.

So steht bei einer Kante mit Pfeilspitze zwischen zwei Knoten die Form --> für die normale Strichstärke, ==> erzeugt einen dickeren Strich und -.-> eine gepunktete Linie. Zwischen dem Knotentext und dem Beginn beziehungsweise dem Ende der Kante muss zwar kein Leerzeichen stehen, mit Leerzeichen sieht die Beschreibung aber lesbarer aus. Den Beschreibungstext zur Kante schließen Sie entweder in Pipe-Zeichen ein (Berlin --> | A 13 | Dresden) oder schreiben ihn direkt in die Kante (Berlin -- A 13 --> Dresden).

Knotenbezeichner mit Sonderzeichen schließen Sie in Anführungszeichen ein. Geben Sie einen Bezeichner in der Form D[Wohnzimmer] an, merkt sich Mermaid die Abkürzung (hier D), die Sie dann später als Referenz verwenden können. Die Art der Klammern entscheidet über die Darstellung des Knotens: Eckige Klammern erzeugen Rechtecke, geschweifte Klammern Rhomben, und runde Klammern sorgen für Rechtecke mit abgerundeten Ecken.

Abbildung 2: Eine Reiseroute als Flussdiagramm mit Mermaid generiert.

Sequenzdiagramm

Ein Sequenzdiagramm beschreibt, wie Prozesse, Programme, Instanzen oder auch Personen miteinander interagieren (Abbildung 3). Nach dem Schlüsselwort sequenceDiagram folgt der Kommunikationsverlauf. Dabei entsprechen Sender und Empfänger den Knoten bei den Graphen, hier gelten die gleichen Regeln zur Schreibweise. Jede Nachricht steht in einer einzelnen Zeile. Über die Pfeilspitze geben Sie an, wer an wen etwas übermittelt. Zwischen dem Empfänger und der Nachricht steht ein Doppelpunkt, ein zusätzliches Leerzeichen verbessert gegebenenfalls die Lesbarkeit.

Abbildung 3: Im Sequenzdiagramm zeichnet Mermaid einen Gesprächsverlauf nach, wie er beispielsweise bei Instant-Messengern üblich ist.

Mermaid geht über einfache Sequenzdiagramme noch hinaus. Dazu gehören Notizen, Aktivierungen, Schleifen, konditionale Blöcke und optionale Angaben. In Abbildung 4 sammelt der Sensor der als Beispiel verwendeten Wetterstation Daten ein und schickt sie jede Minute zur Station, vorausgesetzt er ist aktiv und es besteht eine Verbindung zur Wetterstation. Treten beim Transfer Probleme auf, wiederholt der Sensor die Datenübermittlung.

Eine Schleife zur Wiederholung besteht aus einem loop-end-Block. Eine Bedingung formulieren Sie mithilfe von alt-else-end. Anmerkungen ergänzen Sie mit dem Schlüsselwort Note und einer Positionsangabe. Damit weiß Mermaid, ob es die Notiz im Bild rechts oder links neben dem Knoten platzieren soll.

Abbildung 4: Das Sequenzdiagramm zeigt ein einfaches Ablaufprokoll für eine Wetterstation mit Schleife und if-Bedingung.

Gantt-Diagramm

Mit einem Gantt-Balkendiagramm stellen Sie die zeitliche Abfolge von Ereignissen und Projektschritten dar (Abbildung 5). Nach dem Schlüsselwort gantt vergeben Sie einen Programmtitel (title) und legen das Datumsformat (dateformat) fest. Für jedes Teilprojekt definieren Sie mithilfe des Schlüsselworts section eine Überschrift; in Abbildung 5 heißen die drei Bereiche Auswertung der Wetterdaten, Hardwarebeschaffung und Dokumentation.

Abbildung 5: Darstellung eines Projektablaufs als Gantt-Diagramm, im Beispiel anhand eines möglichen Plans für die Entwicklung einer Wetterstation.

Für jeden Abschnitt des Teilprojekts vergeben Sie einen Titel, der innerhalb der Box erscheint. Passt der Text wegen Überlänge nicht hinein, erscheint er direkt daneben. Jeden Abschnitt definiert ein Identifier – also ein eindeutiger Name – sowie eine Positionsangabe und eine zeitliche Angabe. Als Positionsangaben verwenden Sie wahlweise einen exakten Zeitpunkt oder aber einen Wert der Form after Abschnitt. Somit legen Sie fest, welche Schritte aufeinander aufbauen.

Mermaid einrichten

Zum Redaktionsschluss stand Mermaid noch nicht in paketierter Form in den Repositories der gängigen Distributionen bereit. Zur Installation nutzen Sie daher den Node Package Manager Npm [7] aus dem Javascript-Framework Node.js [8]. Zum Einrichten von Node.js 9 sowie Mermaid unter Debian, Ubuntu oder Linux Mint führen Sie als administrativer Benutzer die fünf Kommandos aus Listing 2 aus.

# curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
# apt-get install nodejs
# apt-get install build-essential
# npm install -g mermaid
# npm install -g mermaid-cli

In den ersten beiden Schritten installieren Sie Node.js. Dann ziehen Sie das Paket build-essential nach, das wichtige Werkzeuge zum Bauen von Software enthält. In den letzten beiden Schritten richten Sie via Npm Mermaid ein, sowohl als Javascript-Framework als auch als Kommandozeilentool.

Nach der Installation steht Ihnen das Kommando mermaid zur Verfügung, dem Sie beim Aufruf das gewünschte Ausgabeformat der Grafik und die Datei mit der Diagrammbeschreibung übergeben. Der folgende Befehl erzeugt beispielsweise aus der Quelltextdatei ablaufdiagramm.txt eine Grafik im PNG-Format:

$ mermaid --png ablaufdiagramm.txt

Um stattdessen eine SVG-Datei zu generieren, geben Sie als Parameter für das Ausgabeformat -s oder --svg an. Im Fall aus unserem Beispiel heißt die erzeugte Bilddatei ablaufdiagramm.png oder bei SVG ablaufdiagramm.svg.

Während der Tests stellten wir fest, dass das Kommandozeilenwerkzeug nur einen Teil der Möglichkeiten mitbringt, welche die Online-Variante bietet. Außerdem unterscheiden sich die erzeugten Bilder von der Ausgabe im Online-Editor: So fehlen zum Beispiel Kantenbeschriftungen und Pfeilspitzen. Auch über Umlaute und Klammern in Beschreibungen stolpert ein lokal eingerichtetes Mermaid konsequent. Als weiterer Schwachpunkt erweist sich die Gestaltung der Diagramme. Das Kommandozeilenwerkzeug erlaubt es derzeit nicht, eigene Stilvorlagen einzubinden. Damit beschränkt sich die Ausgabe auf die mitgelieferten drei Stile.

Ebenfalls einer Revision bedarf das Zusatzmodul Mermaid-Filter [9], das (via Pandoc) Markdown dazu bringt, Mermaid-Anweisungen direkt während des Übersetzens von Markdown nach HTML zu verstehen und somit die Diagramme im Hintergrund zu bauen. Die Beschreibung klingt zwar vielversprechend, aber schon die Installation schlägt unter Debian 8/9 fehl. Die Ursache dafür bleibt unklar.

Um diese Probleme zu umgehen, bleibt nur der Rückgriff auf die Abbildungen im SVG-Format, die der Online-Editor generiert. Dabei gelingt die Automatisierung nur teilweise; hier bleibt nur das Vorbereiten der Bilder oder der Rückgriff auf Graphviz. Möchten Sie den Output von Mermaid anderweitig in Ihren Dokumenten weiterverarbeiten, müssen Sie also zwingend auf das im Grunde weniger geeignete PNG-Format ausweichen.

Sowohl die Online-Version als auch die installierbare Variante produzierte fehlerhafte Vektorgrafiken: Gängige Webbrowser stellen diese zwar halbwegs korrekt dar, doch Programme wie Gimp, LibreOffice Draw, Inkscape (Abbildung 6) oder auch Adobe Illustrator können damit nichts anfangen. Da die weniger fehlerbehaftete Online-Version jedoch nur SVG als Exportformat anbietet, bleibt Ihnen nichts anderes übrig, als mit Screenshots weiterzuarbeiten.

Abbildung 6: Alle von uns getesteten Programme waren nicht in der Lage, die von Mermaid generierte Vektorgrafik korrekt darzustellen.

Fazit

Die Idee hinter Mermaid erscheint bestechend: Man trägt Graphen und Diagramme in Form einer Textbeschreibung zusammen, versieht sie mit einer Stilvorlage und lässt sie dann in ein Bild übersetzen. Dabei sorgt das Textformat nicht nur für eine einfache Schreibweise, sondern ermöglicht auch das unkomplizierte Archivieren der Daten in einem Versionskontrollsystem.

Derzeit trüben jedoch allerlei Fehler das Bild. In der lokal installierten Version trüben eine falsche Darstellung von Sonderzeichen und fehlerhafte Kantenbeschriftungen das Vergnügen, sowohl die lokale als auch die Online-Variante produzieren unbrauchbare Vektorgrafiken. Auch wenn sich das Projekt auf einem guten Weg befindet: Im derzeitigen Zustand eignet es sich nur sehr bedingt für den Produktiveinsatz. Da bleibt nur, auf schnelle Nachbesserung zu hoffen.