Mermaid – Ingo's Blog

Vor einigen Wochen hat ein Kollege in einem internen TecTalk das Tool Mermaid vorgestellt und mein Interesse geweckt.

Mit Mermaid kann man Diagramme erstellen. Das können andere Tools auch, aber Mermaid verfolgt einen eigenen Ansatz: Während andere Tools Diagramme erzeugen, die zB als Bilder (png, jpeg, ...) exportiert und so in anderen Dokumenten verwendet werden können, generiert Mermaid die Diagramme aus Code/Text heraus.

Mermaid
Generate diagrams from markdown-like text.
GitHub - mermaid-js/mermaid: Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown

Dadurch, dass die Diagramme aus Code generiert werden, sind sie sehr leicht anpassbar und können beispielsweise in der Projekt Readme verwendet werden, ohne dass erst das Diagramm in einem eigenen Tool bearbeitet, exportiert, in das Projekt kopiert und in der Readme verlinkt werden muss.

-> "Documentation as Code"

Homepage von Mermaid

GitHub von Mermaid

Live Editor um direkt online loslegen zu können

Klingt auf jeden Fall sehr interessant, auf diese Weise etwas schnell grafisch dokumentieren zu können.

Ich werde die Integration in WordPress, GitHub und Eclipse ansehen.

Beispiel

Diesen Code:

wandelt Mermaid in dieses Diagramm um:

Das Beispiel ist aus dem Live Editor von Mermaid.

WordPress

Die Auswahl an WordPress Plugins für Mermaid ist überschaubar:

Aufgrund der Anzahl aktiver Installationen entscheide ich mich für ein Plugin von Terry Lin. Ich habe erst überlegt, nur das reine Mermaid Plugin zu nehmen, mich dann aber für den kompletten Markdown Editor mit Mermaid Unterstützung entschieden, denn es könnte eine gute Ergänzung zu meinen Code Mirror Block Plugin sein.

WP Githuber MD installiert. Getestet. Deinstalliert.
Problem: Mit dem Plugin kann man NUR noch den Markdown Editor verwenden und nicht mehr den Live Editor von WordPress.
Ich möchte aber gezielt einzelne Markdown bzw. Mermaid Blöcke in meine Seite einbinden und ansonsten den bequemen WYSIWYG Editor verwenden.
Und während ich das hier im WP Editor schreibe, merke ich, dass ich das Plugin noch gar nicht deinstalliert habe und trotzdem kein Markdown verwenden muss. Nach einiger Suche finde ich dann die Möglichkeit, Markdown ein- bzw. auszuschalten. Allerdings geht das immer nur für den ganzen Post. Ich möchte das aber nur für einzelne Blöcke verwenden und nicht deswegen den ganzen Post im Texteditor schreiben müssen.

Nächster Test: WP Mermaid

WP Mermaid is smart enough that loads mermaid.js only when your posts contain Mermaid syntax, by detecting the use of shortcode and block. So it will not be loaded on your website everywhere.
https://www.commoninja.com/discover/wordpress/plugin/wp-mermaid

WP Mermaid Plugin installiert, neuen WP Mermaid Block hinzugefügt, in diesen den Code von der Live Seite hineinkopiert und so sieht es dann aus:

graph TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[fa:fa-car Car]

Funktioniert. Schnell. Einfach. Funktional.

Perfekt, das wollte ich. Plugin bleibt installiert.

GitHub

Wie funktioniert es in GitHub?
Dieser Blogeintrag verrät es: Include diagrams in your Markdown files with Mermaid

Auf die GitHub Seite, eine README.md eines Projektes im Browser im Editor geöffnet, in Edit file den Code eingegeben und im Preview das Diagramm angesehen.

Eclipse

In meinem Eclipse habe ich noch keinen Markdown Editor, wenn ich eine .md Datei öffnen möchte, erscheint der Hinweis:

Da ich bisher selten Markdown verwendet habe, habe ich das ignoriert, auf die Vorschau verzichtet und im Texteditor gearbeitet.

Ich vermute, dass ich Mermaid nur in Markdown Dateien verwenden kann, daher muss ich einen passenden Editor suchen.

Bisher war übrigens ein Markdown Editor in Eclipse enthalten, aber im Release 2022-06 wurde er irrtümlich entfernt.
Über Install New Software ist Mylyn WikiText schnell nachinstalliert.

Der Markdown Editor funktioniert, aber leider Mermaid nicht.

Kein Mermaid Support in Eclipse?
Kann ich mir eigentlich nicht vorstellen, aber ich konnte kein Plugin und keine Anleitung finden.
Ich belasse es erstmal dabei, zur Not erstelle ich die Diagramme online und sehe sie mir dann in GitHub an bis ich eine Lösung für Eclipse gefunden habe.

UPDATE

Das WP Mermaid Plugin scheint nicht richtig zu funktionieren, denn während es im Editor Modus so aussieht, wie es soll, sieht es bei "normalen" Aufruf der Seite verunglückt aus: