Mermaid-Diagramme in Markdown: Flussdiagramme, Sequenzdiagramme und mehr

Diagramme erklären Abläufe, Architekturen und Zeitpläne besser als seitenlanger Text. Wer sie aber in einem Grafikprogramm zeichnet, muss Bilder exportieren, neben der Dokumentation ablegen und bei jeder Änderung alles neu zeichnen.

Mermaid löst dieses Problem: Sie beschreiben das Diagramm in ein paar Zeilen Text in Ihrer Markdown-Datei, und die Vorschau zeichnet es. Das Diagramm steckt in derselben Datei, erscheint in Diffs und lässt sich so leicht ändern wie ein Satz. GitHub, GitLab, Obsidian, viele Dokumentationsgeneratoren und der Markdown Preview Editor stellen Mermaid ohne weitere Einrichtung dar.

So fügen Sie ein Mermaid-Diagramm ein

Legen Sie einen Codeblock an und setzen Sie seine Sprache auf mermaid:

markdown```mermaid
flowchart LR
  A[Schreiben] --> B[Vorschau]
  B --> C{Fertig?}
  C -- ja --> D[Export]
  C -- nein --> A
```

Die Vorschau macht daraus:

Die erste Zeile nennt den Diagrammtyp. Alles danach beschreibt Knoten und Verbindungen.

Flussdiagramme

Flussdiagramme sind der meistgenutzte Diagrammtyp. Die Richtung folgt auf das Schlüsselwort: TD oder TB (von oben nach unten), BT, LR (von links nach rechts) oder RL.

mermaidflowchart TD
  start([Start]) --> input[/Datei lesen/]
  input --> valid{Gültig?}
  valid -- Ja --> save[(In Datenbank speichern)]
  valid -- Nein --> error[Fehler anzeigen]
  error --> input

Die Klammern um eine Beschriftung legen die Form des Knotens fest:

Verbindungen: --> ist ein Pfeil, --- eine Linie ohne Pfeil, -.-> ein gepunkteter Pfeil und ==> ein dicker Pfeil. Eine Beschriftung fügen Sie mit -- text --> oder -->|text| hinzu.

Zusammengehörige Knoten gruppieren Sie mit subgraph:

mermaidflowchart LR
  subgraph Browser
    editor[Editor] --> preview[Vorschau]
  end
  preview --> export[HTML / PDF]

Sequenzdiagramme

Sequenzdiagramme zeigen, wie Beteiligte im Zeitverlauf Nachrichten austauschen – ideal für APIs, Anmeldeabläufe und User Journeys.

mermaidsequenceDiagram
  participant U as Nutzer
  participant A as App
  participant S as Server
  U->>A: Klick auf „Anmelden“
  A->>S: POST /login
  S-->>A: 200 OK + Token
  A-->>U: Dashboard anzeigen
  Note over A,S: Das Token läuft nach 1 Stunde ab

->> ist ein durchgezogener Pfeil (eine Anfrage), -->> ein gestrichelter Pfeil (eine Antwort). Note over, Note left of und Note right of fügen Kommentare hinzu. Mit den Blöcken loop, alt/else und opt stellen Sie Wiederholungen und Verzweigungen dar.

Gantt-Diagramme

Ein Gantt-Diagramm macht aus einer Aufgabenliste einen Zeitplan. Aufgaben können an einem Datum oder after (nach) einer anderen Aufgabe beginnen.

mermaidgantt
  title Dokumentations-Sprint
  dateFormat YYYY-MM-DD
  section Schreiben
  Gliederung     :done,   a1, 2026-10-01, 2d
  Erster Entwurf :active, a2, after a1, 4d
  section Review
  Peer-Review    :        a3, after a2, 3d
  Veröffentlichen :milestone, after a3, 0d

Zustandsdiagramme

Zustandsdiagramme beschreiben, wie etwas zwischen Zuständen wechselt – eine Bestellung, ein Dokument, eine UI-Komponente.

mermaidstateDiagram-v2
  [*] --> Entwurf
  Entwurf --> Review : einreichen
  Review --> Entwurf : Änderungen angefordert
  Review --> Veröffentlicht : freigeben
  Veröffentlicht --> [*]

Kreisdiagramme

Für einen schnellen Überblick über Anteile braucht ein Kreisdiagramm eine Zeile pro Segment:

mermaidpie title Wofür Dokumentationszeit draufgeht
  "Schreiben" : 45
  "Formatieren" : 15
  "Diagramme aktuell halten" : 40

Mermaid unterstützt außerdem Klassendiagramme, Entity-Relationship-Diagramme, Mindmaps, Zeitleisten, Git-Graphen, Quadrantendiagramme und mehr. Die Syntax für jeden Typ ist auf der offiziellen Mermaid-Website dokumentiert.

Tipps für lesbare Diagramme

• Halten Sie es klein. Ein Diagramm mit mehr als 15–20 Knoten wird schwer lesbar. Teilen Sie es in mehrere Diagramme auf, eines pro Idee.
• Wählen Sie die Richtung bewusst. LR passt zu Abläufen mit wenigen Schritten; TD passt zu Hierarchien und langen Abläufen, besonders auf schmalen Bildschirmen.
• Verwenden Sie kurze IDs und lesbare Beschriftungen. Schreiben Sie auth[Sitzung prüfen], statt die Beschriftung als ID zu verwenden – so bleiben die Verbindungen kurz.
• Setzen Sie Beschriftungen mit Sonderzeichen in Anführungszeichen: A["Preis: $5 (inkl. MwSt.)"].
• Fügen Sie Kommentare mit %% am Zeilenanfang hinzu. Sie werden beim Zeichnen ignoriert.
• Sehen Sie sich die Vorschau beim Tippen an. Ein fehlender Pfeil oder eine fehlende Klammer macht das ganze Diagramm kaputt – eine Live-Vorschau erspart viel Rätselraten. Im Markdown Preview Editor wird das Diagramm beim Bearbeiten neu gezeichnet, und die Schaltfläche Mermaid-Diagramm im Erweiterten Editor fügt eine Startvorlage ein.

Dokumente mit Diagrammen teilen

Wenn Sie ein Dokument als HTML oder PDF exportieren, werden die Diagramme als Bilder übernommen – Ihre Leser brauchen also kein Mermaid. Für Formeln neben Ihren Diagrammen lesen Sie, wie Sie mathematische Formeln in Markdown schreiben, und für alles andere – Tabellen, Aufgabenlisten, Hinweisblöcke – halten Sie den Markdown-Spickzettel griffbereit.