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:

Einfaches Flussdiagramm, das einen Entscheidungsprozess zeigt

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:

Architekturdiagramm, das Webserver, Load Balancer und Datenbank zeigt

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:

Kopieren Sie den relevanten Text, der das Konzept beschreibt, das Sie visualisieren möchten
Verwenden Sie eine Eingabeaufforderung wie: „Generieren Sie ein Mermaid-Diagramm basierend auf dieser Beschreibung“
Cursor analysiert den Text und generiert die entsprechende Mermaid-Syntax
Speichern Sie den generierten Mermaid-Code in einer .mmd-Datei
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:

Textdateien nach Beschreibungen durchsuchen, die visualisiert werden könnten
Schlüsselelemente und Beziehungen extrahieren
Entsprechende Mermaid-Syntax basierend auf dem Inhaltstyp generieren
Mermaid CLI automatisch ausführen, um Diagramm-Bilder zu erstellen
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:

Sequenzdiagramm, das den API-Anforderungsfluss zwischen Benutzer, API und Datenbank zeigt

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:

Klassendiagramm, das Kunden- und Bestellklassen mit ihrer Beziehung zeigt

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:

Entitäts-Beziehungs-Diagramm, das die Beziehungen zwischen Kunde, Bestellung, Position und Lieferadresse zeigt

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:

Gantt-Diagramm, das den Projektzeitplan mit Entwicklungsphasen zeigt

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:

Prozessflussdiagramm, das einen Kundenbestell-Workflow zeigt

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:

Dokumentationsdateien auf Änderungen überwacht
KI verwendet, um Inhalte zu identifizieren, die von der Visualisierung profitieren könnten
Entsprechende Mermaid-Syntax basierend auf dem Inhalt generiert
Mermaid CLI automatisch ausführt, um neue Diagramm-Bilder zu erstellen
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

Verwenden Sie aussagekräftige Formen: Mermaid bietet verschiedene Knotenformen, um verschiedene Arten von Komponenten (Datenbanken, Dienste, externe Systeme) zu unterscheiden
Fügen Sie Farbe zur Klarheit hinzu: Verwenden Sie Farben, um verwandte Komponenten zu gruppieren oder wichtige Elemente hervorzuheben
Halten Sie es einfach: Vermeiden Sie überfüllte Diagramme; erstellen Sie stattdessen mehrere fokussierte Diagramme
Verwenden Sie Untergraphen: Gruppieren Sie verwandte Komponenten mit Untergraphen, um logische Grenzen zu zeigen
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.

Documentation

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