Mermaid-Diagramm-Syntax: Beispiele für Markdown und Obsidian

Ein Mermaid-Diagramm ist eine visuelle Darstellung, die mithilfe der Mermaid JS-Bibliothek aus Klartext-Code generiert wird. Das Open-Source-Projekt Mermaid wurde um 2014 von Knut Sveidqvist ins Leben gerufen und hat sich zum Standard für textbasierte Diagramme in der Softwaredokumentation entwickelt. Im Jahr 2026 rendern wichtige Plattformen wie GitHub, GitLab und verschiedene Dokumentationstools die Mermaid-Syntax von Haus aus.

Dieser Leitfaden erklärt die Mermaid-Syntax, die wichtigsten Diagrammtypen, das Rendering in Markdown und Obsidian, Exportoptionen sowie häufige Fehlerquellen.

So sieht die grundlegende Syntax aus:

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

Der „Diagrams as Code“-Ansatz verbessert die Wartbarkeit durch Versionskontrolle und vereinfacht die Zusammenarbeit in Entwicklungsteams. Die folgenden Abschnitte behandeln gängige Diagrammtypen, die Schritt-für-Schritt-Erstellung und den Export von Diagrammen für Stakeholder, die statische Bilder bevorzugen.

Mermaid Syntax Cheat Sheet

Diagramm	Start-Schlüsselwort	Typischer Verwendungszweck
Flussdiagramm	flowchart TD oder flowchart LR	Prozesse und Entscheidungen
Sequenzdiagramm	sequenceDiagram	Anfragen, Antworten und Dienst-Interaktionen
Entity-Relationship	erDiagram	Datenbank-Entitäten und Beziehungen
Zustand	stateDiagram-v2	Status- und Lebenszyklusänderungen
Gantt	gantt	Meilensteine und Zeitpläne
Klasse	classDiagram	Domänen- und Objektmodelle

Jeder Mermaid-Block benötigt genau ein Start-Schlüsselwort. Knoten-IDs sollten kurz und stabil bleiben; sichtbare Beschriftungen können längeren, gut lesbaren Text enthalten.

Was ist ein Mermaid-Diagramm und warum sollten Sie es verwenden?

Ein Mermaid-Diagramm wird aus einer leichtgewichtigen Textsyntax generiert, die von der JavaScript-Bibliothek Mermaid interpretiert wird. Anstatt eine Drag-and-Drop-Benutzeroberfläche zu verwenden, schreiben Sie Mermaid-Diagrammcode, den die Bibliothek in SVG-Grafiken umwandelt.

Wie Mermaid-Code zu Grafiken wird:

• graph TD; A –> B; wird als Flussdiagramm von oben nach unten gerendert

• sequenceDiagram-Blöcke werden zu Sequenzdiagrammen, die Nachrichtenflüsse anzeigen

• erDiagram-Definitionen erzeugen Entity-Relationship-Diagramme

Die wichtigsten Vorteile von textbasierten Diagrammen:

• Menschenlesbarer Klartext, den jeder bearbeiten kann

• Git-freundliche Diffs, die genau zeigen, was geändert wurde

• Einfachere Code-Reviews in Pull-Requests

• Keine proprietären Diagrammdateien, die verwaltet werden müssen

Konkrete Anwendungsfälle für 2026:

• Dokumentation eines Microservice-Authentifizierungsflusses mit Sequenzdiagrammen

• Kartierung von CI/CD-Pipelines vom Commit bis zur Produktionsbereitstellung

• Planung von Produktstart-Meilensteinen für Q2 2026 mit Gantt-Diagrammen

Mermaid-Diagramme fügen sich natürlich in Markdown-basierte Dokumentationen, interne Wikis und Entwicklerportale ein und vereinfachen Dokumentationsprozesse in Ihrer gesamten Organisation.

Kerntypen von Mermaid-Diagrammen

Mermaid unterstützt eine breite Palette an Diagrammtypen. Dieser Abschnitt bietet einen praktischen Überblick über die nützlichsten Typen anstelle einer erschöpfenden Referenz.

Wichtigste Diagrammtypen:

Typ	Schlüsselwort	Am besten geeignet für
Flussdiagramme	graph TD / flowchart LR	Prozessabläufe, Entscheidungsbäume
Sequenzdiagramme	sequenceDiagram	API-Aufrufe, Dienst-Interaktionen
Klassendiagramme	classDiagram	Objektmodelle, Domänendesign
Zustandsdiagramme	stateDiagram-v2	Lebenszyklus-Zustände, Workflows
Entity-Relationship-Diagramme	erDiagram	Datenbank-Schema-Design
User Journey	journey	Kundenerfahrungs-Mapping
Gantt-Diagramme	gantt	Projekt-Zeitpläne, Roadmaps
Kreisdiagramme	pie	Proportionale Datenvisualisierung
Git-Graphen	gitGraph	Branching-Strategien

Praxisbeispiele:

• Sequenzdiagramme für Abläufe Frontend → API Gateway → Payment Service API

• Gantt-Diagramme für Ihre Feature-Roadmap für Q2 2026 mit Abhängigkeiten

• Zustandsdiagramme für den Bestell-Lebenszyklus: ausstehend → bezahlt → versendet → zugestellt

Flussdiagramme, Sequenzdiagramme, ER-Diagramme und Zustandsdiagramme sind für Softwareteams am gebräuchlichsten. Produkt- und Betriebsteams neigen in der Regel zu User-Journey-, Gantt- und Kreisdiagrammen für Kunden- und Geschäftsprozesse.

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

So erstellen Sie Mermaid-Diagramme

Das schnelle Erstellen von Flussdiagrammen beginnt mit dem Verständnis der Grundstruktur. Sie können Diagramme mit jedem Texteditor und der Mermaid-Syntax erstellen.

Schritt-für-Schritt-Prozess:

1. Beginnen Sie mit einem Diagramm-Schlüsselwort (graph TD, sequenceDiagram, gantt)

2. Definieren Sie Knoten oder Teilnehmer mit IDs und Beschriftungen

3. Verbinden Sie Elemente mit Pfeilen oder Beziehungen

4. Fügen Sie nach Bedarf Beschriftungen und Gruppierungen hinzu

Hier ist ein vollständig funktionierendes Flussdiagramm für einen Anmeldevorgang:

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

Pfeiltypen und Beschriftungen:

• –> erzeugt einen standardmäßigen gerichteten Pfeil

• –>|label| fügt Bedingungstext zu Verbindungen hinzu

• — zeichnet eine Linie ohne Pfeilspitze

• -.-> erzeugt einen gepunkteten Pfeil für indirekte Beziehungen

Mermaid ordnet Knoten automatisch mithilfe von ELK-Layout-Algorithmen an. Konzentrieren Sie sich auf logische Struktur und Benennung statt auf manuelle Positionierung – Sie müssen keinen zusätzlichen Code für die Platzierung schreiben.

Wo Sie Mermaid-Diagramme im Jahr 2026 verwenden können

Viele gängige Plattformen unterstützen Mermaid mittlerweile entweder nativ oder über Erweiterungen, was den Einstieg sehr einfach macht.

Wichtigste Umgebungen:

• GitHub und GitLab: Natives Rendering in README.md, Dokumentationen, Issues und Wikis

• Generatoren für statische Websites: Docusaurus, MkDocs und Sphinx mit Erweiterungen

• Interne Entwicklerportale: Backstage und benutzerdefinierte React-Apps

• Notiz-Tools: Notion und Obsidian mit integrierter Unterstützung für Mermaid-Diagramme

Visual Studio Code und JetBrains IDEs unterstützen die Live-Vorschau über Erweiterungen, sodass Sie Diagramme bereits beim Tippen visualisieren können. Dies hilft, Syntaxfehler vor dem Commit von Änderungen abzufangen.

Manche Plattformen wie Confluence Cloud erfordern Marketplace-Add-ons. Teams speichern Diagramme häufig extern in Code-Repositories und legen exportierte Bilder für eine breitere Sichtbarkeit daneben ab.

Rendern von Mermaid-Diagrammen auf verschiedenen Plattformen

Beim Rendern wird Mermaid-Text in visuelle SVG/HTML-Grafiken umgewandelt. Die Methode hängt davon ab, wie das Mermaid-Diagramm mit Ihrer Host-Plattform zusammenarbeitet.

Das allgemeine Muster: Platzieren Sie Mermaid-Code in abgegrenzten Codeblöcken mit der Sprachkennung mermaid. GitHub, GitLab und Dokumentationsgeneratoren rendern diese Blöcke automatisch, wenn sie im Browser angezeigt werden.

Für die lokale Entwicklung bieten Erweiterungen oder Plugins eine Live-Vorschau. Aktivieren Sie in der Sphinx-basierten Dokumentation das Rendering über Erweiterungen wie sphinxcontrib-mermaid, die während des Builds generierte Diagramme verarbeiten.

Rendern von Mermaid in Markdown-Dateien

So rendern Sie Mermaid in Markdown:

1. Verwenden Sie drei Backticks, um einen Codeblock zu öffnen

2. Geben Sie mermaid als Sprachkennung an

3. Fügen Sie Ihre Diagrammdefinition ein

4. Schließen Sie mit drei Backticks

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub, GitLab und moderne Dokumentationsseiten unterstützen dieses Muster direkt

• Testen Sie das Rendering in einer Vorschau-Umgebung, bevor Sie in die Produktion mergen

• Das Standarddesign von Mermaid-Diagrammen eignet sich gut für die meiste Dokumentation

Rendern von Mermaid in Obsidian

Obsidian rendert Mermaid aus einem abgegrenzten mermaid-Codeblock in der Leseansicht und der Live-Vorschau. Die Mermaid-Unterstützung ist integriert, sodass Sie kein Community-Plugin für ein einfaches Diagramm benötigen.

Wenn ein Diagramm nicht gerendert wird:

1. Bestätigen Sie, dass die öffnende Zeile exakt ```mermaid lautet.
2. Überprüfen Sie die erste Zeile auf ein gültiges Diagramm-Schlüsselwort wie flowchart LR.
3. Ersetzen Sie beschriftungsintensive Zeichen durch Anführungszeichen, zum Beispiel A["Review: blocked?"].
4. Reduzieren Sie das Beispiel auf zwei Knoten und fügen Sie dann Zeilen hinzu, bis die fehlerhafte Syntax erscheint.
5. Testen Sie, ob Ihre installierte Obsidian-Version die neuere Mermaid-Syntax unterstützt, die Sie kopiert haben.

Für weitere Obsidian-spezifische Markdown-Erweiterungen nutzen Sie das Obsidian Spickzettel für grundlegende Textformatierung.

Rendern von Mermaid in IDEs und lokalen Tools

Das Visual Studio Code Plugin für Mermaid ermöglicht eine parallele Live-Vorschau beim Bearbeiten von Diagrammen. Mehrere Erweiterungen bieten Syntax-Hervorhebung und Reparaturvorschläge für komplexe Diagramme.

JetBrains IDEs bieten ähnliche Funktionen über Plugins, oft einschließlich Fehlerhinweisen und Exportoptionen. Schaltflächen zur Diagrammreparatur in einigen Tools können häufige Syntaxprobleme automatisch beheben.

Lokale Vorschauen helfen, Fehler vor dem Push in Git-Repositories zu erkennen. Standardisieren Sie ein empfohlenes Erweiterungsset in Ihrer Entwickler-Dokumentation.

Exportieren und Teilen von Mermaid-Diagrammen

Während codebasierte Bearbeitungsoptionen für Entwickler gut funktionieren, bevorzugen Stakeholder oft statische Bilder für Microsoft PowerPoint-Präsentationen und Berichte.

Gängige Exportformate:

• PNG: Schnelle Weitergabe über Messaging-Tools

• SVG: Hochwertige, skalierbare Grafiken für Folien

• PDF: Druckbare Dokumentationspakete

Export-Workflows variieren je nach Tool. Einige enthalten eine integrierte Export-Schaltfläche, während andere den Mermaid Chart Editor oder Online-Tools wie den Mermaid Live Editor erfordern. Befehlszeilen-Tools können im Rahmen von CI/CD Bilder aus mehreren Diagrammdateien stapelweise generieren – eine Form der code-gesteuerten Automatisierung.

Bewahren Sie immer die ursprüngliche Mermaid-Quelle neben den exportierten Dateien auf, damit die Diagramme bearbeitbar bleiben.

Konvertieren von Mermaid-Diagrammen in Bildformate

Mini-Workflow mit einem Online-Editor:

1. Öffnen Sie den Mermaid Live Editor in Ihrem Browser

2. Fügen Sie Ihren Mermaid-Code ein oder verwenden Sie Beispieldiagramme als Vorlagen

3. Passen Sie die Stileinstellungen des Mermaid-Diagramms an

4. Konfigurieren Sie bei Bedarf mehrere Themes (Dunkelmodus- und Hellmodus-Optionen verfügbar)

5. Klicken Sie auf „SVG herunterladen“ oder „PNG herunterladen“

Stellen Sie sicher, dass exportierte Diagramme einheitliche Schriftarten und Farben verwenden, die an den Markenrichtlinien ausgerichtet sind. Screenshots von GitHub werden rasterisiert und skalieren möglicherweise nicht gut – verwenden Sie für Präsentationsfolien nach Möglichkeit SVG-Exporte.

Best Practices und Einschränkungen von Mermaid-Diagrammen

Mermaid ist leistungsstark, funktioniert aber am besten mit durchdachtem Umfang und klarer Struktur für Diagrammierungsaufgaben.

Empfehlungen:

• Beschränken Sie jedes Diagramm auf ein einzelnes, fokussiertes Konzept

• Verwenden Sie aussagekräftige Knotenbeschriftungen und einheitliche Benennungsmuster

• Gruppieren Sie verwandte Schritte mit Subgraph-Blöcken

• Halten Sie komplexe Diagramme als separate Dateien, anstatt eine massive visuelle Diagrammsuite zu erstellen

Zu berücksichtigende Einschränkungen:

• Große, dichte Systeme werden als Code schwer verwaltbar

• Die Layoutsteuerung ist approximativ – keine pixelgenaue Positionierung

• Das Styling ist weniger flexibel als bei traditionellen Diagramm-Tools oder einer Whiteboard-Suite

• Nicht ideal für rein visuelles Diagrammieren oder Benutzeroberflächen-Mockups

Verwenden Sie Mermaid für Architekturübersichten und Workflows. Wechseln Sie zu spezialisierten Tools, wenn pixelgenaue Layouts oder komplexe Netzwerktopologien erforderlich sind. Ein visueller Diagrammeditor kann für bestimmte Anwendungsfälle weiterhin erforderlich sein.

Schneller Einstieg mit Mermaid-Diagrammen

Aktions-Checkliste für neue Benutzer:

1. Wählen Sie einen Diagrammtyp (meist Flussdiagramme, um einfache Prozesse darzustellen)

2. Installieren Sie eine Erweiterung mit visueller Editor- oder KI-Chat-Unterstützung oder öffnen Sie den Mermaid Live Editor

3. Zeichnen Sie einen realen Prozess aus Ihrem aktuellen Projekt – Ihre Bereitstellungs-Pipeline für 2026 eignet sich hervorragend

4. Iterieren und erweitern Sie Ihr Diagramm, während Sie Codierungssyntax-Muster erlernen

Wichtige Ressourcen:

• Offizielle Mermaid-Dokumentation für eine vollständige Syntaxreferenz

• Mermaid Live Editor zum Experimentieren mit eingebetteten KI-Generierungsfunktionen

• VS Code-Erweiterungen mit Code-Snippets und Vorlagen

• Erwägen Sie ein Basiskonto auf Kollaborationsplattformen für Teamfunktionen

Fügen Sie Ihrem Entwickler-Handbuch einen Abschnitt „Diagramm-Richtlinien“ hinzu, der Namenskonventionen, bevorzugte Diagrammtypen und Diagrammberechtigungen abdeckt. Einige Teams stellen fest, dass natürliche Sprachbeschreibungen in Kombination mit eingebetteten KI-Chat-Tools die Diagrammerstellung für jedes technische Niveau beschleunigen.

Die Einführung von Mermaid-Diagrammen richtet Ihre Dokumentation an denselben Review- und Automatisierungspraktiken aus, die für Quellcode verwendet werden. Egal, ob Sie ein Ingenieur für maschinelles Lernen sind, der Modell-Pipelines dokumentiert, oder der Besitzer eines Projektmanagement-Toolkits, der Workflows abbildet – Mermaid bringt versionskontrollierte Visualisierungen in Ihr Team. Beginnen Sie heute mit einem Diagramm.