Markdown-Dokumentation mit Mermaid
Markdown-Dokumentation mit Mermaid: praktischer Leitfaden mit einfügbarem Demo, Review-Checkliste und Veröffentlichungshinweisen für Markdown mit eingebettetem Mermaid.
Das eigentliche Problem
Markdown-Dokumentation mit Mermaid hilft, wenn ein Diagramm nicht nur ein Bild ist, sondern ein wartbarer Teil der Dokumentation. Die Quelle muss lesbar bleiben, die Vorschau soll Fehler zeigen und der Export muss in README, Wiki oder Blog funktionieren.
Nutze den Workflow für README-Seiten, API-Notizen, RFCs und Help-Center-Artikel. Ziel ist eine kurze Schleife aus Bearbeiten, Vorschau und Review vor der Veröffentlichung.
Ein kleines Demo zum Einfügen
Starte nicht mit dem kompletten Produktionsinhalt. Nutze zuerst einen kleinen Ausschnitt, um Syntax, Labels und Layout zu prüfen.
Wenn die erste Vorschau funktioniert, ergänze echte Servicenamen, Felder, Akteure oder Abhängigkeiten.
# Checkout flow
The API creates an order, then asks the payment service to confirm it.
```mermaid
sequenceDiagram
participant User
participant Store
participant Payment
User->>Store: POST /orders
Store->>Payment: Create payment intent
Payment-->>Store: Confirmed
Store-->>User: Order receipt
```So prüfst du die Vorschau
Prüfe die Vorschau wie ein Teamkollege. Beantwortet sie eine klare Frage? Kann die Quelle später sicher geändert werden?
Bei KI-generierten Inhalten solltest du Namen, Richtung, Gruppierung und fehlende Beziehungen prüfen.
Häufige Fehler
Der häufigste Fehler ist, alles in einem Diagramm erklären zu wollen. Trenne Request-Flow, Datenform, Infrastruktur und Publishing-Ausgabe.
Ein weiterer Fehler ist, nur ein Bild zu exportieren. Speichere den Quelltext zusammen mit SVG oder PNG.
Checkliste vor der Veröffentlichung
Vor der Veröffentlichung: Schärfe prüfen, lange Labels prüfen und ein reproduzierbares Eingabebeispiel zeigen.
Die Seite wirkt stärker, wenn sie Eingabe, Vorschau und die Review-Entscheidung zeigt.