Vollständiger Leitfaden zu Mermaid-Diagrammen

Was ist Mermaid?

Warum Mermaid verwenden?

• Versionskontrolle: Diagramme sind Textdateien und können in Git zusammen mit deinem Code nachverfolgt werden
• Schnelle Updates: Ändere ein paar Zeilen Text statt ganze Diagramme neu zu zeichnen
• Konsistenz: Mermaid übernimmt automatisch Layout und Styling und sorgt für konsistente Diagramme
• Keine Design-Tools nötig: Kein Visio, Lucidchart oder andere teure Tools erforderlich
• Dokumentation als Code: Halte Diagramme im selben Repository wie deine Dokumentation
• Plattformübergreifend: Läuft im Browser und in Node.js und lässt sich in viele Plattformen integrieren
• Kostenlos und Open Source: Keine Lizenzkosten, aktive Community
• Mehrere Diagrammtypen: Unterstützt Flussdiagramme, Sequenzdiagramme, Klassendiagramme und mehr

Unterstützte Diagrammtypen

Mermaid unterstützt eine große Vielfalt an Diagrammtypen für unterschiedliche Dokumentationsanforderungen:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

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

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Einstieg in Mermaid

Bewährte Verfahren

• Halte Diagramme auf ein einzelnes Konzept oder einen Workflow fokussiert
• Nutze aussagekräftige Beschriftungen, die die tatsächliche Geschäftslogik beschreiben
• Zerlege komplexe Diagramme in kleinere, miteinander verknüpfte Diagramme
• Füge Kommentare mit %% hinzu, um komplexe Abschnitte zu erklären
• Verwende konsistente Namenskonventionen in deinen Diagrammen
• Teste deine Diagramme in der Zielumgebung, bevor du sie finalisierst
• Füge bei Bedarf Richtungsangaben (TD, LR) hinzu, um das Layout zu steuern
• Verwende Subgraphs, um zusammengehörige Knoten in Flussdiagrammen zu gruppieren
• Setze Styling-Optionen sparsam ein, um die Lesbarkeit zu erhalten
• Versionskontrolliere deine Diagramm-Quelldateien zusammen mit deinem Code

Häufige Anwendungsfälle

Weitere Ressourcen

• Offizielle Mermaid-Dokumentation
• Mermaid GitHub-Repository
• Mermaid Syntax-Referenz