Technische Diagramme veralten oft, weil für deren Bearbeitung das Suchen der ursprünglichen Designdatei, das Öffnen einer separaten Anwendung und das Exportieren eines anderen Bildes erforderlich ist.Mermaid geht einen anderen Weg: Das Diagramm wird als Text definiert und neben der Dokumentation abgelegt.
Um Mermaid zu Markdown hinzuzufügen, platzieren Sie die Diagrammdefinition innerhalb eines umzäunten Codeblocks mit dem mermaid Sprachkennung.Benutzen Sie die Mermaid-Diagrammvorschau um die Syntax lokal darzustellen, Fehler zu korrigieren, den vollständigen Markdown-Zaun zu kopieren oder eine SVG-Datei herunterzuladen.
Dieser Leitfaden beginnt mit einem kleinen Flussdiagramm und baut auf Sequenz-, Klassen-, Gantt-, Mindmap- und Entitätsbeziehungsdiagramme auf.
Mermaid in 30 Sekunden
Ein einfacher Mermaid-Block sieht so aus:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
Der Öffnungszaun teilt einem kompatiblen Renderer mit, dass der Inhalt die Syntax Mermaid hat. flowchart LR wählt ein von links nach rechts angeordnetes Flussdiagramm aus.Die restlichen Linien definieren Knoten und Verbindungen.
Wenn das Ziel Mermaid nicht unterstützt, sehen Leser normalerweise einen Codeblock anstelle eines Diagramms.Dieser Fallback bewahrt die Quelle, ersetzt jedoch nicht die Überprüfung der Kompatibilität vor der Veröffentlichung.
Warum textbasierte Diagramme verwenden?
Mermaid ist besonders nützlich, wenn ein Diagramm:
- gehört zur versionierten Dokumentation;
- Änderungen zusammen mit Code oder Prozeduren;
- benötigt aussagekräftige Pull-Request-Unterschiede;
- verwendet Standardformen und -beziehungen;
- sollte ohne eine proprietäre Designdatei bearbeitbar sein;
- muss in hellen und dunklen Themen neu generiert werden.
Es eignet sich weniger für detaillierte Illustrationen, pixelgenaues Layout, freihändige Anmerkungen oder visuelles Design, das eine präzise manuelle Platzierung erfordert.Verwenden Sie in diesen Fällen ein Zeichenwerkzeug und exportieren Sie eine zugängliche SVG-Datei oder ein Bild.
Beispiel 1: Ein Flussdiagramm
Flussdiagramme beschreiben einen Prozess, eine Entscheidung oder eine Routing-Regel.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Schlüsselsyntax:
TDbedeutet von oben nach unten.LRbedeutet von links nach rechts.[Text]erstellt einen rechteckigen Prozessknoten.{Text}erstellt einen Entscheidungsknoten.-->erstellt eine gerichtete Verbindung.-->|Label|fügt Text zu einer Verbindung hinzu.
Verwenden Sie stabile, kurze Node-IDs wie z A or validate.Halten Sie die sichtbare Beschriftung in Klammern, damit eine Änderung des Wortlauts nicht die Änderung jeder Verbindung erfordert.
Fügen Sie einen Untergraphen hinzu
Untergraphengruppenbezogene Schritte:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Verwenden Sie Untergraphen, wenn die Gruppierung Eigentum, Systemgrenzen oder Phasen kommuniziert.Fügen Sie keine Box nur zur Dekoration hinzu.
Beispiel 2: Ein Sequenzdiagramm
Sequenzdiagramme zeigen Interaktionen in zeitlicher Reihenfolge.Sie funktionieren gut für API-Anrufe, Authentifizierung, Browser-Workflows und ereignisgesteuerte Systeme.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Gemeinsame Pfeile:
->>sendet eine solide Nachricht.-->>sendet eine gestrichelte Antwort.participantdeklariert ein System oder einen Dienst.actordeklariert eine menschliche oder externe Rolle.autonumberbeschriftet Interaktionen in der Reihenfolge.
Konzentrieren Sie sich auf ein Szenario.Ein Sequenzdiagramm, das versucht, jede Alternative und jede interne Funktion darzustellen, ist schwerer zu verstehen als der Code.
Einen alternativen Pfad anzeigen
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Gebrauch alt, else, und end für sinnvolle Zweige.Wenn der Zweig mehrere Seiten mit Erläuterungen erfordert, verlinken Sie unter dem Diagramm auf Prosa.
Beispiel 3: Ein Klassendiagramm
Klassendiagramme beschreiben Typen, Eigenschaften, Operationen, Vererbung und Beziehungen.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
Dieses Beispiel besagt dies MarkdownDocument erbt von Document.Verwenden Sie Klassendiagramme für ein konzeptionelles Modell und nicht als automatischen Ersatz für eine vollständige API-Referenzdokumentation.
Gute Klassendiagramme lassen Details weg, die dem Leser nicht helfen, das Design zu verstehen.Durch die Anzeige aller privaten Felder kann das Diagramm zu einer weniger durchsuchbaren Version des Quellcodes werden.
Beispiel 4: Ein Gantt-Diagramm
Gantt-Diagramme zeigen Aufgaben im Zeitverlauf.Sie sind nützlich für Release-Pläne, Migrationen und Dokumentationsprojekte.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Halten Sie Datumsangaben explizit und verwenden Sie Aufgaben-IDs, wenn eine Aufgabe von einer anderen abhängt.Denken Sie daran, dass sich ein in der Dokumentation gespeichertes Diagramm nicht selbst aktualisiert, wenn sich der tatsächliche Projektzeitplan ändert.Weisen Sie den Besitz zu, um die Datei auf dem neuesten Stand zu halten.
Beispiel 5: Eine Mind Map
Mindmaps organisieren Ideen rund um ein zentrales Thema.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Mind Maps sind am effektivsten bei der Planung oder als allgemeiner Überblick.Für präzise Beziehungen sind sie weniger nützlich, da die Baumstruktur eine Hierarchie implizieren kann, in der sich die tatsächlichen Konzepte überschneiden.
Beispiel 6: Ein Entity-Relationship-Diagramm
ER-Diagramme beschreiben Datenentitäten und ihre Beziehungen.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Verwenden Sie ein ER-Diagramm, um das Modell zu erläutern, und ein Schema oder eine Migrationsdatei, um die Implementierung zu definieren.In einem Diagramm können Indizes, Einschränkungen und Felder weggelassen werden, die für die aktuelle Erklärung nicht relevant sind.
Vorschau Mermaid vor der Veröffentlichung
Das direkte Schreiben von Diagrammen in ein langes Markdown-Dokument erschwert die Isolierung von Syntaxfehlern.Eine fokussierte Vorschauschleife ist schneller:
- Öffnen Sie die Mermaid-Diagrammvorschau.
- Fügen Sie nur die Diagrammdefinition ohne den äußeren Codezaun ein.
- Rendern Sie das Diagramm.
- Lesen Sie etwaige Syntaxfehler und korrigieren Sie den referenzierten Bereich.
- Kopieren Sie den generierten eingezäunten Markdown.
- Laden Sie die SVG-Datei herunter, wenn das Ziel ein statisches Asset benötigt.
- Testen Sie den endgültigen Markdown auf seiner realen Plattform.
Die Vorschau wird in Ihrem Browser mit einer strengen Sicherheitskonfiguration gerendert.Diagrammrückrufe und andere interaktive Verhaltensweisen können deaktiviert sein, auch wenn eine andere Mermaid-Installation dies zulässt.Dieses konservative Verhalten ist für ein allgemeines Vorschautool angemessen.
Häufige Mermaid-Fehler
Der Diagrammtyp fehlt
Falsch:
A --> B
Richtig:
flowchart LR
A --> B
Die erste Zeile identifiziert die Diagrammgrammatik.
Satzzeichen in einer Beschriftung unterbrechen das Parsen
Komplexe Labels zitieren:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
Dies ist besonders nützlich für Klammern, Satzzeichen und Beschriftungen, die der Syntax ähneln.
Ein reservierter Word wird unerwartet verwendet
Mermaid Grammatiken haben Schlüsselwörter.In der offiziellen Flussdiagrammdokumentation wird ausdrücklich vor Kleinschreibung gewarnt end kann ein Flussdiagramm zerstören.Schreiben Sie es groß oder platzieren Sie den sichtbaren Text innerhalb einer Knotenbeschriftung in Anführungszeichen:
flowchart LR
Start --> Finish["End"]
Der Codezaun ist falsch
Der Sprachbezeichner gehört unmittelbar nach den öffnenden Backticks:
```mermaid
flowchart LR
A --> B
```
Den gesamten Zaun nicht einrücken, es sei denn, die umgebende Markdown-Syntax erfordert dies.
Es funktioniert auf einer Plattform, aber nicht auf einer anderen
Mermaid entwickelt sich weiter und Plattformen können verschiedene Renderer, Versionen, Sicherheitseinstellungen und aktivierte Diagrammtypen verwenden.Eine von der neuesten Mermaid-Version unterstützte Syntaxfunktion schlägt möglicherweise auf einer Plattform fehl, die eine andere Implementierung oder eine ältere Version verwendet.
Bevorzugen Sie eine weithin unterstützte Syntax für Dokumente, die zwischen Plattformen verschoben werden.Testen Sie erweiterte Formen, Themen, Anweisungen und neuere Diagrammtypen an jedem erforderlichen Ziel.
Plattformkompatibilität
Kompatibilität sollte eher getestet als angenommen werden:
| Plattform | Aktueller dokumentierter Ansatz | Wichtiger Hinweis |
|---|---|---|
| GitHub | Benutzen Sie einen eingezäunten Bereich mermaid block | GitHub Dokumente, die in Markdown-Dateien, Issues, Diskussionen, Pull Requests und Wikis gerendert werden |
| GitLab | Verwenden Sie einen Mermaid-Codeblock in GitLab Flavored Markdown | GitLab dokumentiert seine unterstützte Mermaid-Version;Selbstverwaltete Installationen können abweichen |
| Obsidian | Benutzen Sie einen eingezäunten Bereich mermaid Block in einer Notiz | Obsidians Renderer und unterstützte Funktionen können sich zwischen den Versionen ändern |
| Material für MkDocs | Konfigurieren Sie einen Mermaid benutzerdefinierten Zaun | Die Integration nativer Themes erfordert eine Dokumentation pymdownx.superfences configuration |
| Allgemeiner Markdown-Parser | Zeigt oft nur Code an | Mermaid-Rendering erfordert normalerweise eine JavaScript-Integration oder ein Build-Plugin |
Überprüfen Sie die aktuelle offizielle Dokumentation, bevor Sie sich auf eine neuere Funktion verlassen:
- GitHub: Diagramme erstellen
- GitLab Flavored Markdown
- Obsidian: Erweiterte Formatierungssyntax
- Material für MkDocs: Diagramme
- Mermaid Syntaxreferenz
Für eine von Ihnen kontrollierte Dokumentationsseite pinnen Sie die Mermaid-Abhängigkeitsversion an und testen Sie Upgrades.Andernfalls kann eine geringfügige Syntaxänderung die Diagramme auf der gesamten Website verändern.
Mermaid und Barrierefreiheit
Ein gerendertes SVG teilt seine Bedeutung nicht automatisch jedem Leser mit.Betrachten Sie das Diagramm als visuelle Zusammenfassung und geben Sie eine gleichwertige Erklärung in ähnlicher Prosa.
Fügen Sie für das frühere Konvertierungsflussdiagramm Text hinzu wie:
Der Benutzer wählt eine DOCX-Datei aus.Gültige Dateien werden lokal konvertiert und zur Überprüfung angezeigt;Ungültige Dateien führen zu einem Fehler.Der Benutzer kann dann den überprüften Markdown kopieren oder herunterladen.
Barrierefreiheitspraktiken:
- stellt vor, was das Diagramm erklärt;
- fassen die Schlussfolgerung nach komplexen Diagrammen zusammen;
- kodieren Bedeutung nicht allein durch Farbe;
- verwenden lesbare Beschriftungen anstelle interner Abkürzungen;
- sorgen für einen ausreichenden Kontrast bei hellen und dunklen Themen;
- Vermeiden Sie Diagramme, die eine präzise Mausinteraktion erfordern.
- bietet eine Text- oder Tabellenalternative für wesentliche Informationen;
- Exportieren Sie SVG mit Vorsicht, wenn die statische Datei einen zugänglichen Namen tragen muss.
Der Quellcode ist für Autoren nützlich, für Leser jedoch nicht unbedingt eine gute Textalternative.
Diagramme entwerfen, die lesbar bleiben
Behalten Sie einen Zweck pro Diagramm bei
Ein Diagramm sollte eine Frage wie „Was passiert nach einer fehlgeschlagenen Anfrage?“ beantworten.oder „Welcher Dienst besitzt die einzelnen Datenspeicher?“Wenn es versucht, das gesamte System zu erklären, teilen Sie es auf.
Bevorzugen Sie kurze Bezeichnungen
Formulieren Sie ausführliche Erklärungen in Prosa.Lange Beschriftungen erzwingen schmale Knoten, umständlichen Zeilenumbruch und große Diagramme auf mobilen Bildschirmen.
Verwenden Sie die Richtung absichtlich
Der Fluss von links nach rechts funktioniert gut für kurze Prozesse und Anforderungspfade.Der Durchfluss von oben nach unten passt oft besser zu schmalen Bildschirmen.Sehen Sie sich beide in der Vorschau an, bevor Sie einen Commit durchführen.
Visuelle Gestaltung einschränken
Benutzerdefinierte Farben können zu Konflikten mit Dark Mode- oder Plattformthemen führen.Beginnen Sie mit den Standardeinstellungen des Renderers.Fügen Sie Stile nur hinzu, wenn sie eine Bedeutung vermitteln und in allen erforderlichen Themen lesbar bleiben.
Halten Sie die Quelle in der Nähe ihrer Erklärung
Speichern Sie den Mermaid-Block nach Möglichkeit in derselben Markdown-Datei.Dadurch ändern sich Prosa und Diagramm gemeinsam in einer Rezension.
Mermaid vs. ein statisches Bild
Wählen Sie Mermaid, wenn:
- das Diagramm ändert sich häufig;
- Quellunterschiede sind wertvoll;
- Das Layout verwendet Standarddiagrammtypen.
- Die Veröffentlichungsplattform gibt Mermaid zuverlässig wieder.
Wählen Sie SVG oder PNG, wenn:
- Das Design erfordert ein präzises manuelles Layout.
- das Ziel gibt Mermaid nicht wieder;
- Das genaue Erscheinungsbild muss festgelegt bleiben;
- Für die externe Freigabe ist ein eigenständiges Asset erforderlich.
Ein nützlicher Hybrid besteht darin, die Mermaid-Quelle beizubehalten und eine SVG-Datei für Ziele zu exportieren, die sie nicht rendern können.Bewahren Sie die Quelle neben dem exportierten Asset auf und dokumentieren Sie, wie Sie es neu generieren.
Gebrauch Markdown in Bild für gemeinsam nutzbare gerenderte Markdown-Inhalte oder laden Sie SVG direkt von herunter Mermaid-Diagrammvorschau wenn das Diagramm selbst das Asset ist.
FAQ
Gehört Mermaid zum Standard Markdown?
Nr. A eingezäunt mermaid -Block ist eine Erweiterung, die von kompatiblen Anwendungen und Build-Systemen erkannt wird.Ein einfacher Markdown-Parser kann es als gewöhnlichen Code rendern.
Rendert GitHub Mermaid-Diagramme?
Ja.Die Dokumentation von GitHub beschreibt das Rendern von Mermaid in Markdown-Dateien und mehreren Kollaborationsoberflächen.Testen Sie die neuere Syntax, da GitHub den bereitgestellten Renderer und die Sicherheitseinstellungen steuert.
Kann ich Mermaid in Obsidian verwenden?
Obsidians offizielle Hilfedokumente Mermaid-artige umzäunte Diagrammblöcke in Notizen.Die Funktionsunterstützung kann sich je nach Renderer der Anwendung ändern. Überprüfen Sie daher komplexe oder neu eingeführte Diagrammtypen in Ihrer installierten Version.
Kann Mermaid die Architekturdokumentation ersetzen?
Nein. Ein Diagramm ist eine Ansicht eines Systems.Kombinieren Sie es mit Entscheidungen, Eigentümern, Einschränkungen, Fehlerverhalten und Links zu maßgeblichen Schnittstellen oder Schemata.
Warum wird mein Diagramm im Dunkelmodus anders gerendert?
Plattformen können unterschiedliche Mermaid-Themen, CSS-Variablen, Schriftarten und Hintergründe anwenden.Vermeiden Sie fest codierte Farben, bis Sie beide Themes getestet haben.
Soll ich exportierte SVG-Dateien festschreiben?
Übertragen Sie eine SVG-Datei, wenn das Veröffentlichungsziel ein statisches Asset benötigt oder das gerenderte Ergebnis stabil bleiben muss.Behalten Sie außerdem die Mermaid-Quelle und einen dokumentierten Regenerationsprozess bei, um ein Driften der beiden Versionen zu verhindern.
Ist Mermaid sicher für vertrauliche Diagramme?
Die Vertraulichkeit hängt vom Redakteur und dem Veröffentlichungsworkflow ab.Die Vorschau von WordToMD rendert das Diagramm in Ihrem Browser, aber die Veröffentlichung von Markdown oder SVG in einem Repository oder einer Site unterliegt den Zugriffskontrollen dieses Ziels.
Schlußfolgerung
Mermaid macht Diagramme wartbar, da die Quelle mit dem Markdown lebt.Beginnen Sie mit einem kleinen eingezäunten Block, wählen Sie den Diagrammtyp aus, der zur Frage passt, zeigen Sie eine Vorschau der Syntax an und testen Sie sie im endgültigen Renderer.Verwenden Sie Prosa, um die wesentliche Bedeutung zu erklären, und exportieren Sie SVG, wenn ein Ziel ein statisches Asset benötigt.
Probieren Sie die Beispiele im aus Mermaid-Diagrammvorschau, bearbeiten Sie die umgebende Dokumentation im Markdown Herausgeberund halten Sie das Diagramm so fokussiert, dass ein zukünftiger Mitwirkender es verstehen und aktualisieren kann, ohne die gesamte Seite neu zeichnen zu müssen.