Mermaid-Syntax-Spickzettel

Das kürzeste Diagramm, das funktioniert

Ein Flowchart braucht eine Deklarationszeile und einen Pfeil. TD steht für top-down (von oben nach unten); für links-nach-rechts nimm LR, was sich für breite Prozesse besser eignet.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Ship it]
  B -->|No| A

A, B und C sind Knoten-IDs — interne Namen, die nie angezeigt werden. Der Text in den Klammern ist die Beschriftung, und der Klammer-Stil bestimmt die Form.

Knotenformen

Die Form wird durch das Klammernpaar um die Beschriftung bestimmt. Diese hier lohnt es sich zu merken:

💡Setze die Beschriftung in Anführungszeichen, wenn sie Klammern, Doppelpunkte oder Anführungszeichen enthält: A["Load (raw) data"]. Ohne Anführungszeichen interpretiert der Parser deine Satzzeichen als Syntax.

Pfeile

Auch die Pfeillänge hat Bedeutung: --> ist ein Rang, ---> schiebt das Ziel einen Rang weiter nach unten. Das ist die einfachste Layout-Kontrolle, die Mermaid bietet.

Gruppierung mit Subgraphen

Ein subgraph zeichnet eine beschriftete Box um Knoten. Subgraphen können verschachtelt werden, und Pfeile dürfen ihre Grenzen frei überqueren.

flowchart LR
  subgraph api["API"]
    H[Handler] --> S[(Postgres)]
  end
  subgraph worker["Worker"]
    Q[Queue] --> W[Job]
  end
  H --> Q

Farbe und Styling

style färbt einen einzelnen Knoten. classDef plus class färbt eine ganze Gruppe davon — das ist ab drei oder vier Knoten die bessere Wahl.

flowchart TD
  A[OK] --> B[Failed]
  style A fill:#16a34a,stroke:#333,color:#fff
  classDef bad fill:#dc2626,stroke:#333,color:#fff
  class B bad

Farben sind Teil des Diagramm-Quelltexts, überstehen also den Export und wandern mit der Datei mit. Nichts hier hängt von einer Theme-Einstellung im Tool ab, das es rendert.

Ein Beispiel pro Diagrammtyp

Sequenzdiagramm

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: request
  API->>DB: query
  DB-->>API: rows
  API-->>User: response

Klassendiagramm

classDiagram
  class Animal {
    +String name
    +move()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

Zustandsdiagramm

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Idle: stop
  Running --> [*]: finish

Entity-Relationship-Diagramm

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }

Gantt-Diagramm

gantt
  title Project
  dateFormat YYYY-MM-DD
  section Phase 1
  Task 1 :a1, 2026-01-01, 5d
  Task 2 :after a1, 5d

Wo Mermaid von sich aus rendert

• GitHub — ein umschlossener ```mermaid-Block rendert in Issues, Pull Requests, Kommentaren und README-Dateien.
• GitLab — derselbe umschlossene Block, in Issues, Merge Requests und im Wiki.
• Notion — ein Code-Block mit der Sprache Mermaid rendert neben der Quelle.
• Obsidian — ein umschlossener Mermaid-Block rendert im Vorschaumodus.
• Docs-Seiten — Docusaurus, MkDocs Material und VitePress unterstützen alle Mermaid-Blöcke.

Das ist der eigentliche Grund, Diagramme als Mermaid statt als Bild zu pflegen: Das Diagramm lebt in derselben Textdatei wie das, was es beschreibt, und ein Code-Review sieht, was sich darin geändert hat.