866 lines
22 KiB
Markdown
866 lines
22 KiB
Markdown
|
||
# ⚙️ Mermaid Crashkurs
|
||
|
||
## 📄 **Mermaid Cheat Sheet (Deutsch)**
|
||
|
||
## ⚓ Inhalt
|
||
|
||
- [⚙️ Mermaid Crashkurs](#️-mermaid-crashkurs)
|
||
- [📄 **Mermaid Cheat Sheet (Deutsch)**](#-mermaid-cheat-sheet-deutsch)
|
||
- [⚓ Inhalt](#-inhalt)
|
||
- [➖ Was ist Mermaid](#-was-ist-mermaid)
|
||
- [➖ Was macht Mermaid?](#-was-macht-mermaid)
|
||
- [➖ Vorteile](#-vorteile)
|
||
- [➖ Typische Anwendungsfälle](#-typische-anwendungsfälle)
|
||
- [➖ Beispiel](#-beispiel)
|
||
- [➖ Beispiel-Code: Summiere eine Liste](#-beispiel-code-summiere-eine-liste)
|
||
- [Diagramme](#diagramme)
|
||
- [➖ Flussdiagramm (`flowchart`)](#-flussdiagramm-flowchart)
|
||
- [➖ Klassendiagramm (`classDiagram`)](#-klassendiagramm-classdiagram)
|
||
- [➖ Zustandsdiagramm (`stateDiagram`)](#-zustandsdiagramm-statediagram)
|
||
- [➖ Entscheidungsdiagramm (`flowchart` mit Bedingungen)](#-entscheidungsdiagramm-flowchart-mit-bedingungen)
|
||
- [➖ Subgraphen (z. B. Module, Gruppen)](#-subgraphen-zb-module-gruppen)
|
||
- [➖ Weitere: Gantt-, Pie- \& ER-Diagramme](#-weitere-gantt--pie---er-diagramme)
|
||
- [➖ Erklärung](#-erklärung)
|
||
- [➖ Visualisierung/ Rendering](#-visualisierung-rendering)
|
||
- [➖ Gängige Symbole (Unicode sicher)](#-gängige-symbole-unicode-sicher)
|
||
- [➖ Diagramm-Layout und Styling-Optionen](#-diagramm-layout-und-styling-optionen)
|
||
- [Mermaid `style`-Eigenschaften (Übersicht)](#mermaid-style-eigenschaften-übersicht)
|
||
- [Beispiel mit mehreren Eigenschaften](#beispiel-mit-mehreren-eigenschaften)
|
||
- [➖ Interaktive Features \& Erweiterte Syntax](#-interaktive-features--erweiterte-syntax)
|
||
- [➖ Klickbare Knoten](#-klickbare-knoten)
|
||
- [➖ Tooltip mit `click` kombinieren](#-tooltip-mit-click-kombinieren)
|
||
- [➖ Ankerpunkte / Subgraph-Steuerung](#-ankerpunkte--subgraph-steuerung)
|
||
- [➖ Weitere Optionen](#-weitere-optionen)
|
||
- [➖ Anmerkungen](#-anmerkungen)
|
||
- [➖ Testing-Setup \& CI-Integration](#-testing-setup--ci-integration)
|
||
- [➖ Mermaid CLI (`@mermaid-js/mermaid-cli`)](#-mermaid-cli-mermaid-jsmermaid-cli)
|
||
- [➖ Beispiel: Einfache .mmd-Datei](#-beispiel-einfache-mmd-datei)
|
||
- [➖ Typische Optionen](#-typische-optionen)
|
||
- [➖ Automatisierung mit Makefile](#-automatisierung-mit-makefile)
|
||
- [➖ CI-Beispiel (GitHub Actions)](#-ci-beispiel-github-actions)
|
||
- [📌 Hinweis](#-hinweis)
|
||
- [➖ Diagramm-Export / Automatisierung](#-diagramm-export--automatisierung)
|
||
- [➖ Export mit Mermaid CLI](#-export-mit-mermaid-cli)
|
||
- [➖ Installation](#-installation)
|
||
- [🛠 Typische Optionen](#-typische-optionen-1)
|
||
- [➖ Beispiel: SVG aus `.mmd` erzeugen](#-beispiel-svg-aus-mmd-erzeugen)
|
||
- [➖ Struktur im Projekt](#-struktur-im-projekt)
|
||
- [➖ Makefile-Beispiel](#-makefile-beispiel)
|
||
- [➖ GitHub Actions-Beispiel](#-github-actions-beispiel)
|
||
- [➖ Hinweise](#-hinweise)
|
||
- [➖ Template \& Projektintegration](#-template--projektintegration)
|
||
- [➖ Ablauf](#-ablauf)
|
||
- [🛠 Tools](#-tools)
|
||
- [Links](#links)
|
||
- [✏️ Notizen bei Erstellung dieses Dokuments](#️-notizen-bei-erstellung-dieses-dokuments)
|
||
|
||
---
|
||
|
||
## ➖ Was ist Mermaid
|
||
|
||
**Mermaid** ist eine deklarative Scriptsprache zur Erstellung von Diagrammen und Visualisierungen auf Basis von **einfachem Text**. Sie wurde entwickelt, um komplexe Abläufe, Strukturen und Beziehungen direkt aus Quellcode-artiger Notation zu **automatisch generierten Diagrammen** umzuwandeln – ohne grafische Tools oder spezielle Software.
|
||
|
||
---
|
||
|
||
### ➖ Was macht Mermaid?
|
||
|
||
- Generiert **Flowcharts**, **Klassendiagramme**, **Zustandsautomaten**, **Gantt-Diagramme**, **Entscheidungsbäume**, **Entity-Relationship-Diagramme** u.v.m.
|
||
- Nutzt eine **einfach lesbare Syntax** ähnlich wie Markdown oder Code
|
||
- Eignet sich ideal zur Dokumentation von **Software**, **Prozessen**, **Systemarchitekturen** und **Ablauflogiken**
|
||
- Kann direkt in viele Tools eingebettet werden (z. B. GitHub, VS Code, MkDocs, Obsidian)
|
||
- Unterstützt **Versionierung**, **Code-first-Dokumentation** und ist vollständig **plattformunabhängig**
|
||
|
||
---
|
||
|
||
### ➖ Vorteile
|
||
|
||
- Kein Drag & Drop – **alles in Text**
|
||
- Leicht in Git-Projekte integrierbar
|
||
- Wartbar, automatisierbar, CI/CD-fähig
|
||
- Unterstützt **Unicode-Symbole**, Farben, Subgraphen und Labels
|
||
- Ideal für Entwickler, Techniker und Dokumentationszwecke
|
||
|
||
---
|
||
|
||
### ➖ Typische Anwendungsfälle
|
||
|
||
- Darstellung von **Funktionsabläufen**
|
||
- Visualisierung von **Code-Logik** und **Bedingungen**
|
||
- Modellierung von **Klassenhierarchien** oder **Zuständen**
|
||
- Erstellung von **technischen Spezifikationen**
|
||
- Unterstützung bei **Team-Kommunikation** und **Code Reviews**
|
||
|
||
---
|
||
|
||
**Beispieldiagram:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
%% Grundstruktur
|
||
Start([Start])
|
||
Entscheidung{Bedingung erfüllt?}
|
||
Aktion1[Aktion bei Ja]
|
||
Aktion2[Aktion bei Nein]
|
||
Ende([Ende])
|
||
|
||
%% Verbindungen
|
||
Start --> Entscheidung
|
||
Entscheidung -- Ja --> Aktion1 --> Ende
|
||
Entscheidung -- Nein --> Aktion2 --> Ende
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
### ➖ Beispiel
|
||
|
||
Exemplarisch ein kleines Programm als **Mermaid-Ablaufdiagramm**.
|
||
Wir nehmen dazu ein simples Beispiel in Python:
|
||
|
||
#### ➖ Beispiel-Code: Summiere eine Liste
|
||
|
||
**Python-Code:**
|
||
|
||
```python
|
||
def summiere_liste(liste):
|
||
summe = 0
|
||
for zahl in liste:
|
||
summe += zahl
|
||
return summe
|
||
```
|
||
|
||
**Das gleiche in Mermaid-Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Start([Start])
|
||
Init[summe = 0]
|
||
Schleife{Liste leer?}
|
||
Hole[Hole nächstes Element]
|
||
Addiere[summe += zahl]
|
||
Ende([return summe])
|
||
|
||
Start --> Init --> Schleife
|
||
Schleife -- Nein --> Hole --> Addiere --> Schleife
|
||
Schleife -- Ja --> Ende
|
||
```
|
||
|
||
**Ergibt dann gerendert:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([Start])
|
||
Init[summe = 0]
|
||
Schleife{Liste leer?}
|
||
Hole[Hole nächstes Element]
|
||
Addiere[summe += zahl]
|
||
Ende([return summe])
|
||
|
||
Start --> Init --> Schleife
|
||
Schleife -- Nein --> Hole --> Addiere --> Schleife
|
||
Schleife -- Ja --> Ende
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
### Diagramme
|
||
|
||
#### ➖ Flussdiagramm (`flowchart`)
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Start([Start])
|
||
Entscheidung{Bedingung erfüllt?}
|
||
Aktion1[Aktion bei Ja]
|
||
Aktion2[Aktion bei Nein]
|
||
Ende([Ende])
|
||
|
||
Start --> Entscheidung
|
||
Entscheidung -- Ja --> Aktion1 --> Ende
|
||
Entscheidung -- Nein --> Aktion2 --> Ende
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([Start])
|
||
Entscheidung{Bedingung erfüllt?}
|
||
Aktion1[Aktion bei Ja]
|
||
Aktion2[Aktion bei Nein]
|
||
Ende([Ende])
|
||
|
||
Start --> Entscheidung
|
||
Entscheidung -- Ja --> Aktion1 --> Ende
|
||
Entscheidung -- Nein --> Aktion2 --> Ende
|
||
```
|
||
|
||
**Richtungen:**
|
||
|
||
- `TD` = oben nach unten (Top → Down)
|
||
- `LR` = links nach rechts (Left → Right)
|
||
- `BT` = unten nach oben (Bottom → Top)
|
||
- `RL` = rechts nach links (Right → Left)
|
||
|
||
**Knotenformen:**
|
||
|
||
| Syntax | Bedeutung |
|
||
| --------------- | -------------------- |
|
||
| `A[Text]` | Rechteck (Prozess) |
|
||
| `A((Text))` | Kreis (Start/Ende) |
|
||
| `A{Bedingung?}` | Raute (Entscheidung) |
|
||
| `A>"Text"]` | Subprozess |
|
||
| `A["Text"]` | Textblock |
|
||
|
||
**Verbindungen:**
|
||
|
||
- `A --> B` → gerichteter Pfeil
|
||
- `A -- Text --> B` → beschrifteter Pfeil
|
||
- `A -.-> B` → gestrichelte Linie
|
||
- `A ===> B` → dicker Pfeil
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
#### ➖ Klassendiagramm (`classDiagram`)
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
classDiagram
|
||
class Fahrzeug {
|
||
+String marke
|
||
+fahre()
|
||
}
|
||
class Auto {
|
||
+int tueranzahl
|
||
}
|
||
Fahrzeug <|-- Auto
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Fahrzeug {
|
||
+String marke
|
||
+fahre()
|
||
}
|
||
class Auto {
|
||
+int tueranzahl
|
||
}
|
||
Fahrzeug <|-- Auto
|
||
```
|
||
|
||
**Beziehungen:**
|
||
|
||
- `<|--` → Vererbung
|
||
- `*--` → Komposition
|
||
- `o--` → Aggregation
|
||
- `--` → Assoziation
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
#### ➖ Zustandsdiagramm (`stateDiagram`)
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
stateDiagram-v2
|
||
[*] --> Wartend
|
||
Wartend --> Aktiv : start()
|
||
Aktiv --> Wartend : stop()
|
||
Aktiv --> [*]
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Wartend
|
||
Wartend --> Aktiv : start()
|
||
Aktiv --> Wartend : stop()
|
||
Aktiv --> [*]
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
#### ➖ Entscheidungsdiagramm (`flowchart` mit Bedingungen)
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
A{Ist x > 10?}
|
||
A -- Ja --> B[Ausgabe: Groß]
|
||
A -- Nein --> C[Ausgabe: Klein]
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A{Ist x > 10?}
|
||
A -- Ja --> B[Ausgabe: Groß]
|
||
A -- Nein --> C[Ausgabe: Klein]
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
#### ➖ Subgraphen (z. B. Module, Gruppen)
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
subgraph ModulA
|
||
A1 --> A2
|
||
end
|
||
subgraph ModulB
|
||
B1 --> B2
|
||
end
|
||
A2 --> B1
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph ModulA
|
||
A1 --> A2
|
||
end
|
||
subgraph ModulB
|
||
B1 --> B2
|
||
end
|
||
A2 --> B1
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
#### ➖ Weitere: Gantt-, Pie- & ER-Diagramme
|
||
|
||
- `gantt` für Zeitplanung
|
||
- `pie` für Verhältnisdarstellungen
|
||
- `erDiagram` für Entitäten & Datenbanken
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
### ➖ Erklärung
|
||
|
||
- **Start** → Initialisierung
|
||
- **Schleife** prüft, ob noch Elemente vorhanden sind
|
||
- Wenn **Nein**, wird das nächste Element geholt und aufaddiert
|
||
- Wenn **Ja**, wird die Schleife beendet und `summe` zurückgegeben
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ➖ Visualisierung/ Rendering
|
||
|
||
- [x] **<https://mermaid.live>**
|
||
- Vollständig browserbasiert, keine Installation
|
||
- Sofortige Vorschau
|
||
- Export als PNG, SVG, PDF
|
||
- Speichern & Teilen von Diagrammen
|
||
- [x] **Eingebettet in HTML**
|
||
- Die Datei [`demo.html`](demo.html) zeigt wie dies erfolgen könnte.
|
||
- [x] **In VS-Code** (nur lokal)
|
||
- 📦 „**Markdown Preview Mermaid Support**" (Autor: bierner oder vhatpal)
|
||
Damit kannst du in Markdown-Dateien Mermaid-Diagramme live in der Vorschau anzeigen lassen:
|
||
Öffne .md-Datei
|
||
> `Ctrl+Shift+V` oder rechtsklick → Markdown-Vorschau öffnen
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ➖ Gängige Symbole (Unicode sicher)
|
||
|
||
| Symbol | Bedeutung |
|
||
| ------ | ---------------- |
|
||
| ⚙ | Prozess |
|
||
| ✔ | Erfolgreich |
|
||
| ✖ | Fehler / Abbruch |
|
||
| ℹ | Info / Hinweis |
|
||
| ⏳ | Warten / Delay |
|
||
|
||
```plaintext (mermaid)
|
||
flowchart LR
|
||
Start((⚙ Start))
|
||
Prozess1[✔ OK]
|
||
Fehler[✖ Fehler]
|
||
Start --> Prozess1 --> Fehler
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Start((⚙ Start))
|
||
Prozess1[✔ OK]
|
||
Fehler[✖ Fehler]
|
||
Start --> Prozess1 --> Fehler
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ➖ Diagramm-Layout und Styling-Optionen
|
||
|
||
Mermaid erlaubt die **Anpassung von Farben, Fonts, Ausrichtung und Stilen** über einfache Inline-Befehle:
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Start([Gestylter Start])
|
||
style Start fill:#f9f,stroke:#333,stroke-width:2px
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([Gestylter Start])
|
||
style Start fill:#f9f,stroke:#333,stroke-width:2px
|
||
```
|
||
|
||
### Mermaid `style`-Eigenschaften (Übersicht)
|
||
|
||
| Eigenschaft | Beschreibung | Beispiel |
|
||
| ------------------ | ------------------------------------- | ----------------------- |
|
||
| `fill` | Hintergrundfarbe | `fill:#f9f` |
|
||
| `stroke` | Rahmenfarbe | `stroke:#333` |
|
||
| `stroke-width` | Rahmenstärke | `stroke-width:2px` |
|
||
| `color` | Textfarbe | `color:#000000` |
|
||
| `font-size` | Schriftgröße | `font-size:14px` |
|
||
| `font-family` | Schriftart | `font-family:monospace` |
|
||
| `font-weight` | Schriftstil (z. B. `bold`, `normal`) | `font-weight:bold` |
|
||
| `background-color` | Alternativ zu `fill` (seltener nötig) | `background-color:#eee` |
|
||
| `opacity` | Transparenz (0 bis 1) | `opacity:0.8` |
|
||
| `text-align` | Textausrichtung innerhalb des Knotens | `text-align:center` |
|
||
| `rx`, `ry` | Rundung der Ecken | `rx:10`, `ry:10` |
|
||
|
||
### Beispiel mit mehreren Eigenschaften
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Wichtig([⚠ Kritischer Pfad])
|
||
style Wichtig fill:#ffe6e6,stroke:#cc0000,stroke-width:2px,color:#000,font-weight:bold
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Wichtig([⚠ Kritischer Pfad])
|
||
style Wichtig fill:#ffe6e6,stroke:#cc0000,stroke-width:2px,color:#000,font-weight:bold
|
||
```
|
||
|
||
**🔧 Hinweis:**
|
||
|
||
- Die style-Anweisung wirkt nur auf den genannten Knoten (`style <ID>` ...)
|
||
- Du kannst mehrere style-Zeilen einfügen
|
||
- Unterstützt nur Grundwerte, kein CSS-Selektor, kein hover, keine Klassen
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ➖ Interaktive Features & Erweiterte Syntax
|
||
|
||
Mermaid erlaubt einfache Interaktionen direkt im Diagramm. Besonders hilfreich für Dokumentationen, Präsentationen oder klickbare Projektübersichten.
|
||
|
||
---
|
||
|
||
### ➖ Klickbare Knoten
|
||
|
||
**Du kannst Knoten interaktiv machen, indem du sie mit Links versiehst:**
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Info([ℹ Dokumentation])
|
||
click Info "https://example.com/doku" "Mehr zur Doku"
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Info([ℹ Dokumentation])
|
||
click Info "https://example.com/doku" "Mehr zur Doku"
|
||
```
|
||
|
||
> **Hinweis:** Das funktioniert nur in Umgebungen, die `click` unterstützen (z. B. HTML-Embedding oder Mermaid Live Editor, nicht in GitHub-Rendern).
|
||
|
||
---
|
||
|
||
### ➖ Tooltip mit `click` kombinieren
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Hilfe([ℹ Hilfe anzeigen])
|
||
click Hilfe "https://example.com/hilfe" "Öffnet die Hilfeseite"
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Hilfe([ℹ Hilfe anzeigen])
|
||
click Hilfe "https://example.com/hilfe" "Öffnet die Hilfeseite"
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Ankerpunkte / Subgraph-Steuerung
|
||
|
||
**Subgraphen lassen sich interaktiv strukturieren – z. B. als Module oder Zuständigkeiten:**
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TB
|
||
subgraph Backend [Backend-Systeme]
|
||
DB[(PostgreSQL DB)]
|
||
API[REST API]
|
||
end
|
||
|
||
subgraph Frontend [Client]
|
||
UI[Benutzeroberfläche]
|
||
end
|
||
|
||
UI --> API --> DB
|
||
click UI "https://frontend.example.com" "Zur Benutzeroberfläche"
|
||
click DB "https://db-docs.example.com" "DB-Doku"
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Backend [Backend-Systeme]
|
||
DB[(PostgreSQL DB)]
|
||
API[REST API]
|
||
end
|
||
|
||
subgraph Frontend [Client]
|
||
UI[Benutzeroberfläche]
|
||
end
|
||
|
||
UI --> API --> DB
|
||
click UI "https://frontend.example.com" "Zur Benutzeroberfläche"
|
||
click DB "https://db-docs.example.com" "DB-Doku"
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Weitere Optionen
|
||
|
||
| Funktion | Beschreibung | Beispiel |
|
||
|--------------|--------------------------------------|--------------------------------------------------------|
|
||
| `click` | Knoten klickbar machen | `click ID "https://..." "Tooltip"` |
|
||
| `tooltip` | Tooltip anzeigen (oft via `click`) | Bestandteil von `click`, kein eigener Befehl |
|
||
| `linkStyle` | Stil für Link-Linien setzen | `linkStyle 0 stroke:#f66,stroke-width:2px` |
|
||
| `subgraph` | Gruppe von Elementen darstellen | `subgraph Name` … `end` |
|
||
| `style` | Styling eines Knotens | `style KnotenID fill:#eee,stroke:#000` |
|
||
|
||
---
|
||
|
||
### ➖ Anmerkungen
|
||
|
||
- In Markdown-Dokumenten (z. B. GitHub READMEs) **funktionieren `click`-Links meist nicht**, da Mermaid dort ohne JS läuft.
|
||
- Für interaktive Versionen → HTML exportieren oder Mermaid Live Editor nutzen.
|
||
- Tooltips erscheinen nur bei aktiver `click`-Anweisung.
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ➖ Testing-Setup & CI-Integration
|
||
|
||
Mermaid-Diagramme lassen sich auch automatisiert rendern und testen – z. B. in **Build-Skripten**, **Makefiles** oder **CI/CD-Pipelines**. Das ist nützlich, wenn du aus `.mmd`-Quelldateien automatisch **SVGs** oder **PNGs** generieren willst.
|
||
|
||
---
|
||
|
||
### ➖ Mermaid CLI (`@mermaid-js/mermaid-cli`)
|
||
|
||
Das offizielle Node.js-Tool heißt `mmdc` und kann über `npm` installiert werden:
|
||
|
||
```bash
|
||
npm install -g @mermaid-js/mermaid-cli
|
||
```
|
||
|
||
Danach kannst du eine `.mmd`-Quelldatei rendern:
|
||
|
||
```bash
|
||
mmdc -i diagram.mmd -o diagram.svg
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Beispiel: Einfache .mmd-Datei
|
||
|
||
**`diagram.mmd`**:
|
||
|
||
```plaintext
|
||
flowchart TD
|
||
A[Start] --> B[Ende]
|
||
```
|
||
|
||
**Exportbefehl:**
|
||
|
||
```bash
|
||
mmdc -i diagram.mmd -o diagram.svg
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Typische Optionen
|
||
|
||
| Option | Bedeutung |
|
||
|----------------|------------------------------------------|
|
||
| `-i` | Eingabedatei (.mmd) |
|
||
| `-o` | Ausgabedatei (SVG, PNG, PDF möglich) |
|
||
| `-t default` | Theme: `default`, `dark`, `neutral`, `forest` |
|
||
| `--width` | Breite des Diagramms |
|
||
| `--scale` | Skalierung (z. B. für PDF-Ausgabe) |
|
||
|
||
---
|
||
|
||
### ➖ Automatisierung mit Makefile
|
||
|
||
```makefile
|
||
diagram.svg: diagram.mmd
|
||
mmdc -i diagram.mmd -o diagram.svg -t dark
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ CI-Beispiel (GitHub Actions)
|
||
|
||
```yaml
|
||
name: Mermaid Build
|
||
|
||
on: [push]
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
- run: npm install -g @mermaid-js/mermaid-cli
|
||
- run: mmdc -i diagram.mmd -o diagram.svg
|
||
```
|
||
|
||
---
|
||
|
||
### 📌 Hinweis
|
||
|
||
- Mermaid CLI nutzt **Puppeteer (Headless Chromium)**, daher ggf. zusätzliche Abhängigkeiten im CI-System notwendig
|
||
- Mermaid CLI rendert **keine eingebetteten Diagramme** in Markdown – nur `.mmd`-Dateien!
|
||
|
||
**Empfohlene Struktur im Projekt:**
|
||
|
||
```plaintext
|
||
docs/
|
||
diagrams/
|
||
main.mmd
|
||
main.svg
|
||
Makefile
|
||
README.md
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ➖ Diagramm-Export / Automatisierung
|
||
|
||
Mermaid-Diagramme lassen sich automatisch aus Quelltext-Dateien exportieren – ideal für Skripte, Build-Systeme oder CI/CD-Pipelines.
|
||
|
||
---
|
||
|
||
### ➖ Export mit Mermaid CLI
|
||
|
||
Die **offizielle Mermaid CLI** (`@mermaid-js/mermaid-cli`) erlaubt den Export von `.mmd`-Quelldateien in verschiedene Formate:
|
||
|
||
```bash
|
||
mmdc -i diagram.mmd -o diagram.svg
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Installation
|
||
|
||
Installieren über npm:
|
||
|
||
```bash
|
||
npm install -g @mermaid-js/mermaid-cli
|
||
```
|
||
|
||
---
|
||
|
||
### 🛠 Typische Optionen
|
||
|
||
| Option | Bedeutung |
|
||
|--------------------|--------------------------------------------|
|
||
| `-i` | Eingabedatei (`.mmd`) |
|
||
| `-o` | Ausgabedatei (`.svg`, `.png`, `.pdf`) |
|
||
| `-t dark` | Theme (`default`, `dark`, `forest`, `neutral`) |
|
||
| `--scale` | Skalierung der Ausgabe (z. B. `--scale 2`) |
|
||
| `--width`, `--height` | Feste Größenangabe |
|
||
|
||
---
|
||
|
||
### ➖ Beispiel: SVG aus `.mmd` erzeugen
|
||
|
||
**Datei `ablauf.mmd`:**
|
||
|
||
```plaintext
|
||
flowchart TD
|
||
Start --> Verarbeitung --> Ende
|
||
```
|
||
|
||
**Exportbefehl:**
|
||
|
||
```bash
|
||
mmdc -i ablauf.mmd -o ablauf.svg -t default
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Struktur im Projekt
|
||
|
||
Empfohlene Projektstruktur:
|
||
|
||
```plaintext
|
||
docs/
|
||
diagrams/
|
||
diagram.mmd
|
||
diagram.svg
|
||
Makefile
|
||
README.md
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Makefile-Beispiel
|
||
|
||
```makefile
|
||
diagram.svg: diagram.mmd
|
||
mmdc -i diagram.mmd -o diagram.svg -t dark
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ GitHub Actions-Beispiel
|
||
|
||
```yaml
|
||
name: Mermaid-Diagramm-Export
|
||
|
||
on: [push]
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
- run: npm install -g @mermaid-js/mermaid-cli
|
||
- run: mmdc -i diagram.mmd -o diagram.svg -t forest
|
||
```
|
||
|
||
---
|
||
|
||
### ➖ Hinweise
|
||
|
||
- Mermaid CLI basiert auf Puppeteer (Headless Chrome) → CI-Systeme benötigen ggf. zusätzliche Abhängigkeiten
|
||
- Nur `.mmd`-Dateien werden unterstützt – kein Inline-Markdown
|
||
- Ideal für automatisierten SVG-Export für Dokumentation oder statische Webseiten
|
||
|
||
---
|
||
|
||
## ➖ Template & Projektintegration
|
||
|
||
**Ein Mini-Template als Startpunkt für neue Projekte:**
|
||
|
||
## ➖ Ablauf
|
||
|
||
**Code:**
|
||
|
||
```plaintext (mermaid)
|
||
flowchart TD
|
||
Init((Start))
|
||
Task1[Prozess 1]
|
||
Task2[Prozess 2]
|
||
Done((Fertig))
|
||
Init --> Task1 --> Task2 --> Done
|
||
```
|
||
|
||
**Ausgabe:**
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Init((Start))
|
||
Task1[Prozess 1]
|
||
Task2[Prozess 2]
|
||
Done((Fertig))
|
||
Init --> Task1 --> Task2 --> Done
|
||
```
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## 🛠 Tools
|
||
|
||
| Tool | Vorschau | Markdown-kompatibel | Bemerkung |
|
||
| ------------------------------------ | -------- | ------------------- | -------------------------------- |
|
||
| [mermaid.live](https://mermaid.live) | ✔ | ✔ | Online-Editor |
|
||
| VS Code + Plugin | ✔ | ✔ | Markdown Preview Mermaid Support |
|
||
| GitHub README | ✔ | ✔ | nur in Repos |
|
||
| mkdocs-material | ✔ | ✔ | für Doku-Webseiten |
|
||
|
||
### Links
|
||
|
||
- Mermaid auf GitHub <https://github.com/mermaid-js/>
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|
||
|
||
## ✏️ Notizen bei Erstellung dieses Dokuments
|
||
|
||
> `extensions.json` erstellt mit `code --list-extensions > extensions.txt`
|
||
|
||
Hier ist ein **deutschsprachiges Mermaid Cheat Sheet** mit den wichtigsten Diagrammtypen, Syntaxelementen und Beispielen – vollständig in Markdown, damit du es direkt in deine Projekte einbinden kannst.
|
||
|
||
[⚓ Inhalt](#-inhalt)
|
||
|
||
---
|