Automatisierung der Diagramm-Erstellung mit Mermaid CLI und KI-Tools

Diagramme zu erstellen war schon immer einer meiner am wenigsten Lieblingsteile der Dokumentation. Ich habe Stunden damit verschwendet, Kästchen herumzuschieben und hatte am Ende immer noch etwas, das amateurhaft aussah. Das änderte sich, als ich Mermaid entdeckte. In diesem Beitrag teile ich mit, wie ich Mermaid CLI verwende, um Diagramme nur mit Text zu erstellen, und wie Tools der künstlichen Intelligenz diesen Prozess vollständig verändert und optimiert haben.

Was ist Mermaid?

Mermaid ist ein kostenloses Open-Source-Tool, das Text in Diagramme umwandelt, ähnlich wie Markdown Text in formatierten Inhalt umwandelt. Es ist vollständig kostenlos unter der MIT-Lizenz, sodass Sie es für die Arbeit oder private Zwecke verwenden können, ohne sich um Lizenzkosten sorgen zu müssen. Es kann verwendet werden, um alle Arten von Diagrammen zu erstellen, wie zum Beispiel:

• Flussdiagramme
• Sequenzdiagramme
• Klassendiagramme
• Entitäts-Beziehungs-Diagramme
• Gantt-Diagramme
• Kreisdiagramme
• User Journey Maps
• Git-Diagramme
• Zustandsdiagramme
• Und viele mehr

Was ich am meisten liebe, ist, dass ich nie wieder Kästchen herumziehen muss. Ich schreibe einfach Text, und Mermaid erstellt das Diagramm. Nach Jahren des Kampfes mit traditionellen Diagrammtools fühlt sich dieser Ansatz wie eine Offenbarung an.

Erste Schritte mit Mermaid CLI

Ich habe angefangen, Mermaid im Browser zu verwenden, aber die CLI-Version (Command Line Interface) ist der Ort, an dem die wahre Magie passiert. Sie ermöglicht es Ihnen, Ihre Textdiagramme in tatsächliche Bilddateien umzuwandeln, die Sie in Dokumente, Präsentationen oder wo auch immer einfügen können. Und es ist super einfach zu bedienen.

Die grundlegende Syntax für die Verwendung von Mermaid CLI lautet:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png

Dieser Befehl:

• npx @mermaid-js/mermaid-cli: Führt das Mermaid CLI-Tool aus, ohne eine globale Installation zu benötigen
• -i diagram.mmd: Gibt die Eingabedatei an, die Ihre Mermaid-Diagrammdefinition enthält
• -o diagram.png: Legt den Namen und das Format der Ausgabedatei fest (in diesem Fall PNG)

Sie können auch SVG-Dateien generieren, die skalierbar sind und perfekt für die Webnutzung geeignet sind:

npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

Sie können Ihren Mermaid-Code auch schnell online mit Tools wie MermaidChart in der Vorschau anzeigen, was ideal zum Testen und Teilen von Diagrammen ist, ohne etwas installieren zu müssen.

Erstellen Ihres ersten Mermaid-Diagramms

Beginnen wir mit einem einfachen Flussdiagramm. Erstellen Sie eine Datei mit dem Namen flowchart.mmd mit diesem Inhalt:

flowchart TD
A[Start] --> B{Entscheidung}
B -->|Ja| C[Prozess 1]
B -->|Nein| D[Prozess 2]
C --> E[Ende]
D --> E

Generieren Sie nun ein PNG-Bild dieses Diagramms:

npx @mermaid-js/mermaid-cli -i flowchart.mmd -o flowchart.png

Dies erstellt ein sauberes, professionell aussehendes Flussdiagramm, das einen einfachen Entscheidungsprozess zeigt, wie diesen:

Sie können diesen Ansatz für jede Art von Diagramm verwenden, die Mermaid unterstützt.

Wenn Sie beispielsweise eine Systemarchitektur visualisieren müssen (wie ich es kürzlich getan habe), können Sie etwas Ähnliches erstellen:

flowchart TD
Client([Webbrowser]) --HTTP/HTTPS--> LB[Load Balancer]
LB --> API1[API-Server 1]
LB --> API2[API-Server 2]
API1 --> DB[(Datenbank)]
API2 --> DB
API1 --> Cache[(Redis-Cache)]
API2 --> Cache

Was dieses Diagramm erzeugt:

Wie KI die Diagrammerstellung verbessert

Hier wird künstliche Intelligenz zum Game-Changer. Anstatt manuell Mermaid-Diagramme zu schreiben, können KI-Tools wie Cursor und Windsurf Textbeschreibungen analysieren und automatisch Diagrammdefinitionen für Sie generieren.

Ich musste kürzlich ein Architekturdiagramm für ein AWS + Drupal-Projekt mit einer komplexen Architektur erstellen. Ohne KI hätte es erhebliche Zeit gekostet, alle Komponenten und Verbindungen zu kartieren. Stattdessen habe ich die Projektspezifikationen an Cursors KI-Assistenten weitergegeben, ihn gebeten, die Systemkomponenten und ihre Beziehungen zu extrahieren, und ich habe Mermaid-Code erhalten, der mir geholfen hat, das Diagramm effizienter zu erstellen.

Verwendung von Cursors KI zur Generierung von Diagrammen

Cursor ist eine IDE mit leistungsstarker KI, die sowohl Code als auch natürliche Sprache versteht. Seine Fähigkeit, technische Beschreibungen zu interpretieren und in strukturierte Mermaid-Syntax umzuwandeln, ist bemerkenswert. Hier ist mein typischer Workflow:

1. Kopieren Sie den relevanten Text, der das Konzept beschreibt, das Sie visualisieren möchten
2. Verwenden Sie eine Eingabeaufforderung wie: „Generieren Sie ein Mermaid-Diagramm basierend auf dieser Beschreibung“
3. Cursor analysiert den Text und generiert die entsprechende Mermaid-Syntax
4. Speichern Sie den generierten Mermaid-Code in einer .mmd-Datei
5. Verwenden Sie Mermaid CLI, um ihn in ein Bild umzuwandeln

Sie könnten Cursor beispielsweise mit Anweisungen wie diesen auffordern:

• „Erstellen Sie ein Mermaid-Flussdiagramm, das einen Benutzerregistrierungsprozess zeigt“
• „Generieren Sie ein Mermaid-Sequenzdiagramm für diesen API-Anforderungsfluss“
• „Konvertieren Sie diesen Projektzeitplan in ein Mermaid-Gantt-Diagramm“
• „Erstellen Sie ein Mermaid-Klassendiagramm aus dieser Beschreibung des Domänenmodells“

Innerhalb von Sekunden haben Sie ein vollständiges Mermaid-Diagramm, das Ihr Konzept genau darstellt.

Weiterentwicklung mit Windsurfs KI

Windsurf (von Codeium) nutzt KI, um die Diagramm-Automatisierung noch weiter voranzutreiben. Seine KI-Modelle können ganze Codebasen oder Dokumentationsmengen analysieren, um Skripte zu erstellen, die:

1. Textdateien nach Beschreibungen durchsuchen, die visualisiert werden könnten
2. Schlüsselelemente und Beziehungen extrahieren
3. Entsprechende Mermaid-Syntax basierend auf dem Inhaltstyp generieren
4. Mermaid CLI automatisch ausführen, um Diagramm-Bilder zu erstellen
5. Diese Diagramme in Ihre Dokumente einfügen

Dies schafft einen kontinuierlichen Dokumentationsworkflow, bei dem Ihre Diagramme mit Ihren schriftlichen Inhalten synchron bleiben. Die KI kann erkennen, wenn sich Ihr Code oder Ihre Dokumentation so stark ändert, dass ein Diagramm-Update erforderlich ist, wodurch der gesamte Prozess nahezu „hands-free“ wird.

Fortgeschrittene Diagrammtypen

Mermaid unterstützt viele Diagrammtypen über einfache Flussdiagramme hinaus. Hier sind einige nützliche für die Architekturdokumentation:

Sequenzdiagramme

Perfekt, um zu veranschaulichen, wie Komponenten im Laufe der Zeit interagieren:

sequenceDiagram
participant Benutzer
participant API
participant Datenbank

Benutzer->>API: GET /produkte
API->>Datenbank: Produkte abfragen
Datenbank-->>API: Ergebnisse zurückgeben
API-->>Benutzer: JSON-Antwort

Was dieses Sequenzdiagramm erzeugt:

Klassendiagramme

Ideal, um objektorientiertes Design zu zeigen:

classDiagram
class Bestellung {
    +String id
    +Datum erstelltAm
    +Bestellstatus status
    +gesamtBetragBerechnen()
}
class Kunde {
    +String id
    +String name
    +String email
    +bestellungAufgeben()
}
Kunde "1" -- "viele" Bestellung: platziert

Was dieses Klassendiagramm erzeugt:

Entitäts-Beziehungs-Diagramme

Großartig für Datenbankdesign:

erDiagram
KUNDE ||--o{ BESTELLUNG : platziert
BESTELLUNG ||--|{ POSITION : enthält
KUNDE }|..|{ LIEFERADRESSE : verwendet

Was dieses Entitäts-Beziehungs-Diagramm erzeugt:

Praktische Beispiele

Mermaid CLI kann für verschiedene Visualisierungsanforderungen verwendet werden, einschließlich der Systemarchitekturdokumentation (wie bereits erwähnt), aber auch für:

Projektplanung

Für die Projektplanung können Sie ein Gantt-Diagramm erstellen, das Phasen und Abhängigkeiten zeigt:

gantt
title Projektzeitplan
dateFormat  YYYY-MM-DD
section Forschung
Anforderungsanalyse :a1, 2025-01-01, 10d
Marktforschung       :after a1, 7d
section Entwicklung
Frontend-Entwicklung  :b1, 2025-01-18, 14d
Backend-Entwicklung   :b2, 2025-01-18, 21d
section Testen
Integrationstest   :c1, after b1 b2, 7d
Benutzerakzeptanz       :c2, after c1, 7d

Was diese Zeitplanvisualisierung erzeugt:

Prozessdokumentation

Zur Dokumentation von Geschäftsprozessen kann Mermaid übersichtliche Flussdiagramme erstellen:

flowchart TD
Start([Kundenbestellung]) --> A{Lagerbestand verfügbar?}
A -->|Ja| B[Zahlung bearbeiten]
A -->|Nein| C[Bestellprozess]
B --> D[Produkt versenden]
C --> E[Kunden benachrichtigen]
D & E --> Ende([Bestellung abschließen])

Was diesen Prozessfluss erzeugt:

Zukünftige Möglichkeiten mit KI und Automatisierung

Die Kombination aus Mermaid CLI und KI-Tools eröffnet spannende Möglichkeiten für die Dokumentationsautomatisierung. Ich stelle mir ein System vor, das:

1. Dokumentationsdateien auf Änderungen überwacht
2. KI verwendet, um Inhalte zu identifizieren, die von der Visualisierung profitieren könnten
3. Entsprechende Mermaid-Syntax basierend auf dem Inhalt generiert
4. Mermaid CLI automatisch ausführt, um neue Diagramm-Bilder zu erstellen
5. Diagramme intelligent in die Dokumentation mit dem richtigen Kontext einbettet

Ein solches Setup würde Diagramme ohne manuelles Eingreifen mit der Dokumentation synchron halten. Obwohl ich dieses System noch nicht gebaut habe, machen die aktuellen KI-Tools und Mermaid CLI es durchaus möglich.

Tipps für bessere Diagramme

1. Verwenden Sie aussagekräftige Formen: Mermaid bietet verschiedene Knotenformen, um verschiedene Arten von Komponenten (Datenbanken, Dienste, externe Systeme) zu unterscheiden
2. Fügen Sie Farbe zur Klarheit hinzu: Verwenden Sie Farben, um verwandte Komponenten zu gruppieren oder wichtige Elemente hervorzuheben
3. Halten Sie es einfach: Vermeiden Sie überfüllte Diagramme; erstellen Sie stattdessen mehrere fokussierte Diagramme
4. Verwenden Sie Untergraphen: Gruppieren Sie verwandte Komponenten mit Untergraphen, um logische Grenzen zu zeigen
5. Fügen Sie Titel und Beschreibungen hinzu: Machen Sie Ihre Diagramme selbsterklärend mit klaren Titeln und kurzen Beschreibungen

Zusammenfassend

Mermaid bietet einen praktischen Ansatz zur Diagrammerstellung, der sich gut in Entwicklungsworkshops integriert. Die textbasierte Natur von Mermaid-Diagrammen macht sie versionskontrollfreundlich und einfacher zu pflegen als traditionelle Diagrammformate.

In Kombination mit KI-Tools wird der Prozess noch effizienter. Diese Tools können helfen, Diagrammcode aus Beschreibungen zu generieren, wodurch er auch für diejenigen zugänglich wird, die keine tiefgreifenden technischen Kenntnisse haben.

Hier sind einige abschließende Gedanken zur Verwendung von Mermaid:

• Lernkurve: Die Syntax ist relativ einfach zu erlernen, insbesondere wenn Sie bereits mit Markdown oder anderen textbasierten Formaten vertraut sind.
• Integration: Mermaid-Diagramme funktionieren auf vielen Plattformen, darunter GitHub, Notion und andere Dokumentationssysteme.
• Kosten: Als Open-Source-Tool mit einer MIT-Lizenz ist Mermaid für jeden Zweck kostenlos nutzbar.
• Effizienz: Die textbasierte Diagrammerstellung kann schneller sein als die traditionelle Diagrammerstellung, sobald Sie mit der Syntax vertraut sind.
• Einfache Einrichtung: Die Verwendung von npx zum Ausführen von Mermaid CLI eliminiert Installationsprobleme.

Wenn Sie Ihren Dokumentationsprozess verbessern möchten, sollten Sie Mermaid für Ihr nächstes Projekt ausprobieren. Die Möglichkeit, professionelle Diagramme direkt aus Textbeschreibungen zu erstellen, möglicherweise mit Unterstützung von KI-Tools, könnte Ihre Herangehensweise an die Visualisierung in Ihrer Arbeit verändern.