Mermaid-Diagramme Dokumentarchitektur in Markdown ohne Klicks

Ihr Architekturdiagramm war korrekt, als Sie es zeichneten. Das war drei Sprints her. Heute existiert es in einem gemeinsamen Google-Slide, der niemand aktualisiert, und der Ingenieur, der das Dienstleistungsbauwerk entwickelt hat, hat bereits sein Team gewechselt. Klingt vertraut?

Mermaid-Diagramme drehen dieses Problem auf den Kopf. Statt eine drag-and-drop-Bildfläche außerhalb Ihres Codebases zu verwenden, schreiben Sie Diagramme als Text – als einfache Markdown-Formatierung, die in Ihrem README steht, mit Ihrem Code versioniert wird und überall dort, wo Markdown gerendert wird, angezeigt wird. Wenn die Architektur sich ändert, ändern Sie eine Textdatei. Der Diff erzählt die ganze Geschichte.

Was Mermaid ist (und warum Diagramme als Code wichtig sind)

Mermaid ist eine Open-Source-Diagramm-Programmiersprache, die Diagramme aus reinem Text generiert. Sie schreiben einen Flussdiagramm in einem eingeschlossenen Codeblock; ein Renderer (oder ein Mermaid-bewusstes Viewer) verwandelt es in ein SVG-Diagramm. Keine Konten, keine Exportschritte, keine „das Diagrammformat wird auf diesem Gerät nicht unterstützt“.

Der Ansatz „Diagramme als Code“ erzielt seine Wirkung auf folgende konkrete Weise:

• Versionierung — Diagramme leben in Git. Sie können sie diffen, rückgängig machen und mit demselben PR wie der Code, den sie beschreiben, verknüpfen.
• Keine Abhängigkeit von einem Anbieter — Der Text ist portabel. Wechseln Sie den Renderer, forken Sie den Repository, exportieren Sie in Confluence – die Quelle ist immer lesbar.
• Immer nahe an dem Code — Ein Diagramm in derselben Repository wie das Dienstleistungsbauwerk, das es beschreibt, ist viel wahrscheinlicher, korrekt zu bleiben, als ein Diagramm in einem gemeinsamen Slide-Deck.
• Automatisierungsfreundlich — Sie können Mermaid-Syntax aus Code (Datenbank-Schemata, API-Spezifikationen, CI-Pipelines) mit Skripten oder LLMs generieren.

Bevor Sie in die Diagrammtypen eintauchen, können Sie jedes Mermaid-Format sofort vorab ansehen – ohne lokale Einrichtung – mit dem Mermaid-Diagramm-Renderer auf iotools.cloud. Fügen Sie es ein, sehen Sie das Ergebnis und iterieren Sie. Verwenden Sie es in Kombination mit dieser Anleitung, um jedes Beispiel live auszuführen.

Flussdiagramme: Die Arbeitskraft

Flussdiagramme sind der häufigste Mermaid-Diagramm-Typ und dafür eine gute Grundlage – sie behandeln alles von einfachen Entscheidungsbäumen bis zu komplexen Mehrdienstflüssen. Hier ist das Format, das 90% echter Anwendungsfälle abdeckt:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

Einige Dinge, die über das Flussdiagramm-Format zu wissen sind:

• Richtung: TD (von oben nach unten), LR (von links nach rechts), BT (von unten nach oben), RL (von rechts nach links)
• Knotenformen: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Kantenbeschriftungen: -- label --> oder -->|label|
• Untergraphen: Gruppieren Sie verwandte Knoten visuell

Untergraphen sind besonders nützlich, um Service-Grenzen darzustellen:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Sequenzdiagramme: API-Aufrufflüsse anzeigen

Sequenzdiagramme sind das richtige Werkzeug, wenn Sie die Reihenfolge der Interaktionen zwischen Systemen zeigen müssen – eine API-Aufrufkette, eine Auth-Fluss, eine Webhook-Folge. Sie machen Timing und Verantwortung klar auf eine Weise, die ein Flussdiagramm nicht erreichen kann.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Feste Pfeile (->>) sind Anfragen; gestrichelte Pfeile (-->>) sind Antworten. Die participant Declarations steuern die Reihenfolge, in der die Boxen am oberen Rand des Diagramms erscheinen. Sie können auch actor für menschliche Teilnehmer verwenden, activate/deactivate um Verarbeitungszeit zu zeigen, und loop oder alt Blöcke für bedingte Flüsse.

Entitäts-Beziehungs-Diagramme: Datenbank-Schemata in Dokumentationen

ER-Diagramme gehören in jedes Dienstleistungsdokument, das eine Datenbank-Schema besitzt. Das Mermaid-ER-Format ist sauber und beinhaltet die Kardinalität aus der Box:

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Kardinalitätsnotation: || ist genau eine, o| ist null oder eine, o{ ist null oder viele, |{ ist eine oder viele. Die Beziehungsschrift („places“, „contains“) wird am Ende in Anführungszeichen gesetzt.

Zustandsdiagramme: Workflows und Zustandsmaschinen modellieren

Jedes Mal, wenn Sie ein Objekt haben, das durch verschiedene Zustände wechselt – eine Bestellung, eine Abonnement, ein CI-Auftrag – ist ein Zustandsdiagramm präziser als ein Flussdiagramm. Das Mermaid-Zustandsdiagramm-Format entspricht direkt der Art, wie Sie eine Zustandsmaschine im Code definieren:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] markiert den Start- und Endzustand. Übergänge tragen das Ereignis auf, das sie auslöst. Sie können Zustände für zusammengesetzte Zustände verschachteln und note Blöcke verwenden, um Übergänge mit zusätzlichen Kontext zu annotieren.

Klassen-Diagramme: OOP-Strukturen für Onboarding-Dokumentationen

Klassen-Diagramme sind am nützlichsten, wenn Ingenieure an eine objektorientierte Codebasis eingebunden werden oder wenn ein Domänenmodell dokumentiert wird. Mermaid beinhaltet Vererbung, Schnittstellen, Zusammensetzung und Methodensignaturen:

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +fetch() void
    }
    class Cat {
        +boolean isIndoor
        +purr() void
    }
    Animal <|-- Dog : extends
    Animal <|-- Cat : extends

Sichtbarkeitsmodifikatoren folgen der UML-Standard: + public, - private, # protected. Beziehungspfeile umfassen Assoziation (-->), Vererbung (<|--), Zusammensetzung (*--) und Aggregation (o--).

Wo Mermaid nativ gerendert wird

Der echte Vorteil von Mermaid ist seine native Unterstützung in den bereits verwendeten Tools von Entwicklern:

• GitHub — Mermaid-eingeschlossene Codeblöcke (```mermaid) werden in READMEs, Issues, Pull-Request-Beschreibungen und Wikis ab 2022 automatisch gerendert.
• GitLab — Native Mermaid-Unterstützung in Markdown-Dateien und Wiki-Seiten.
• Notion — Fügen Sie einen Mermaid-Codeblock in einen Codeblock ein, der auf „Mermaid“ eingestellt ist, und es wird inline gerendert.
• VS Code — Die Markdown-Preview-Mermaid-Unterstützung erzeugt Diagramme im integrierten Vorschau-Panel.
• Obsidian — Mermaid wird nativ gerendert, ohne jegliche Erweiterung.
• Docusaurus, MkDocs, Astro — Es gibt Mermaid-Plugins für alle wichtigen statischen Website-Generatoren.
• Confluence — über die Mermaid-Diagramme für Confluence-App.

Wenn Sie Dokumentation schreiben, die in GitHub oder GitLab landet, funktionieren Mermaid-Diagramme aus der Box ohne Konfiguration.

Mängel und Situationen, in denen etwas anderes verwendet werden sollte

Mermaid ist nicht perfekt für jede Situation. Einige Dinge, die zu beachten sind:

• Komplexe Layouts — Das automatische Layout-Algorithmus von Mermaid erzeugt nicht immer saubere Ergebnisse bei großen Graphen. Wenn Sie 50+ Knoten mit vielen überschneidenden Kanten haben, müssen Sie möglicherweise das Diagramm manuell neu strukturieren oder aufteilen.
• Confluence-Rendern — Confluence unterstützt native Mermaid nicht. Sie benötigen eine bezahlte App. Wenn Ihr Team in Confluence lebt, planen Sie dafür oder verwenden Sie draw.io statt.
• Nicht-standardisierte Diagrammtypen — Netzwerke, Bereitstellungsdienste und C4-Architektur-Diagramme erfordern Workarounds oder werden nicht gut unterstützt.
• Styling-Steuerung — Die thematischen Optionen von Mermaid sind begrenzt. Für diagramme mit benutzerdefinierten Farben und Schriftarten werden Sie Zeit verlieren, um mit dem Renderer zu kämpfen.

Die wichtigsten Alternativen, die bekannt sind:

• PlantUML — Älter, verständlicher Syntax, aber umfassendere UML-Unterstützung und bessere Confluence-Integration. Erfordert Java lokal oder einen Server-Renderer.
• D2 — Ein neueres „diagramme als Code“-Tool mit besserer Layoutsteuerung und besseren Behandlungen großer Diagramme. Weniger Ecosystem-Akzeptanz als Mermaid, aber schnell wachsend.
• draw.io / Excalidraw — GUI-Tools, wenn Sie präzise visuelle Kontrolle benötigen und nicht darauf bedacht sind, dass das Diagramm außerhalb der Versionierung existiert.

Für die meisten Entwicklungs-Dokumentationen – Service-READMEs, API-Flüsse, Onboarding-Guides – deckt Mermaid das Nutzungsszenario gut ab und die native GitHub-Unterstützung allein macht es den Lernkurve wert.

Mermaid ohne Installation vorab anzeigen

Wenn Sie mit dem Syntax experimentieren oder ein Diagramm mit jemandem teilen möchten, der kein lokales Renderer-Setup hat, bietet der Mermaid-Diagramm-Renderer auf iotools.cloud eine Live-Vorschau ohne Registrierung, ohne Installation und ohne Konfiguration. Fügen Sie Ihren Mermaid-Code ein, sehen Sie das gerenderte Diagramm und kopieren Sie das Ergebnis.

Es ist nützlich, um die Diagramm-Syntax vor dem Commit zu überprüfen, ein gerendertes Version in einer Slack-Nachricht zu teilen oder ein Diagramm zu prototypisieren, das Sie später in eine README einfügen werden.

Beginnen Sie mit einem Flussdiagramm

Wenn Sie noch nie ein Mermaid-Diagramm geschrieben haben, beginnen Sie mit einem Flussdiagramm. Wählen Sie einen Prozess in Ihrem Codebase, den Sie dokumentieren wollten – eine Anfrage-Lifecycle, ein Hintergrundjob, ein Deploy-Pipeline – und schreiben Sie es in Mermaid-Syntax in den nächsten 10 Minuten. Fügen Sie es in Ihr README in einem ```mermaid Block ein und pushen Sie es. GitHub rendert es automatisch.

Dieses einziges Diagramm, das versioniert ist und neben dem Code, den es beschreibt, existiert, ist wertvoller als ein Slide-Deck, das niemand vertraut.

Das könnte Ihnen auch gefallen