RepoThread Logo
RepoThread
Preise

Schnellstart

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

Einführung und Einsatzmöglichkeiten

Mermaid ist eine JavaScript-basierte Diagrammbibliothek, die Textdefinitionen in SVG-Diagramme umwandelt. Das Projekt besteht aus drei Hauptkomponenten: Deployment, Syntax und Konfiguration (docs/intro/getting-started.md:7-30). Diese Struktur ermöglicht Entwicklern, Diagramme mittels einfacher Textbeschreibungen zu erstellen und in verschiedene Umgebungen zu integrieren.

Für Einsteiger stehen fünf verschiedene Einsatzmöglichkeiten zur Verfügung: die Nutzung des Mermaid Live Editors, des Mermaid Chart Editors, von Plugins und Integrationen, der JavaScript API oder als direkte Abhängigkeit im Projekt. Der Live Editor unter mermaid.live bietet dabei den einfachsten Einstiegspunkt, da keine Installation erforderlich ist und Diagramme direkt im Browser erstellt werden können (docs/intro/getting-started.md:32-55).

Mermaid Live Editor und Chart Editor

Mermaid Live Editor Funktionen

Der Mermaid Live Editor bietet eine Echtzeitvorschau von Diagrammen. Im Code-Panel wird die Mermaid-Syntax eingegeben, während das Preview-Panel das gerenderte Ergebnis anzeigt. Konfigurationsoptionen sind im separaten Configuration-Panel verfügbar und werden direkt auf das Diagramm angewendet (docs/intro/getting-started.md:70-100).

Exportfunktionen:

  • PNG-Export für Rastergrafiken
  • SVG-Export für skalierbare Vektorgrafiken
  • Markdown-Export zur Einbettung in Dokumentation

Der Editor speichert automatisch alle Bearbeitungsschritte im Timeline-Tab des History-Bereichs. Bearbeitungen werden minütlich gespeichert, wobei nur die letzten 30 Bearbeitungen sichtbar bleiben. Alternativ kann der Code manuell über das Save-Symbol gespeichert werden.

Mermaid Chart Editor

Der Mermaid Chart Editor unter mermaid.ai stellt eine erweiterte webbasierte Lösung dar, die vom Mermaid-Team entwickelt wurde. Dieser Editor bietet zusätzliche Funktionen wie KI-gestütztes Diagramming, Zusammenarbeit mehrerer Benutzer in Echtzeit sowie Cloud-Speicherung (docs/intro/getting-started.md:131-146).

Integration über Plugins und native Unterstützung

Verfügbare Plugins

Mermaid kann über Plugins in verschiedene Anwendungen integriert werden. Mermaid Chart Plugins sind verfügbar für:

PlattformPlugin-Typ
ChatGPTKI-Integration
JetBrains IDEEntwicklungsumgebung
Microsoft PowerPointPräsentationssoftware
Microsoft WordTextverarbeitung
Visual Studio CodeCode-Editor

Die vollständige Liste der Community-Plugins und Integrationen ist auf der Integrations-Seite dokumentiert (docs/intro/getting-started.md:148-179).

Native Markdown-Unterstützung

Anwendungen mit nativer Markdown-Unterstützung wie GitHub und GitLab können Mermaid-Diagramme direkt rendern. Die Einbettung erfolgt durch einen mermaid-Codeblock:

markdown
1```mermaid
2flowchart LR
3  A --> B
4```

Diese Methode erfordert keine zusätzliche JavaScript-Einbindung, da die Plattformen die Rendering-Logik serverseitig bereitstellen (docs/intro/getting-started.md:172-179).

JavaScript API Integration

Grundvoraussetzungen

Die Mermaid JavaScript API funktioniert mit gängigen Webservern wie Apache, IIS, Nginx und Node Express. Die API lädt Rendering-Anweisungen aus der mermaid.js-Quelldatei, um Diagramme auf der Seite zu rendern. Internet Explorer wird nicht unterstützt (docs/intro/getting-started.md:181-199).

HTML-Struktur und Initialisierung

Bei der Verwendung der JavaScript API müssen zwei Anweisungen in der HTML-Datei enthalten sein:

  1. Diagramm-Definition: Eingebettet in <pre class="mermaid">-Tags
  2. Mermaid-Import und Initialisierung: Laden der Bibliothek über mermaid.esm.mjs oder mermaid.esm.min.mjs sowie Aufruf von mermaid.initialize()

Beispiel für die Einbettung:

html
1<body>
2  Here is a mermaid diagram:
3  <pre class="mermaid">
4        graph TD
5        A[Client] --> B[Load Balancer]
6        B --> C[Server01]
7        B --> D[Server02]
8  </pre>
9</body>

Jede Diagrammdefinition benötigt separate <pre>-Tags (docs/intro/getting-started.md:200-218).

Programmgesteuerte Initialisierung und Rendering

Die RunOptions-Schnittstelle

Die RunOptions-Schnittstelle definiert Parameter für die programmgesteuerte Diagrammverarbeitung:

ParameterTypBeschreibung
querySelectorstringCSS-Selektor zum Finden von Elementen (Standard: .mermaid)
nodesArrayLikeDirekte Übergabe von DOM-Elementen
postRenderCallbackfunctionCallback nach jedem gerenderten Diagramm
suppressErrorsbooleanUnterdrückt Fehlerausgaben (Standard: false)

Wenn nodes gesetzt ist, wird querySelector ignoriert (packages/mermaid/src/mermaid.ts:45-62).

Die run()-Funktion

Die run()-Funktion durchsucht das Dokument nach Diagrammdefinitionen und rendert diese. Die Funktion markiert verarbeitete Elemente mit dem Attribut data-processed, um mehrfaches Rendern zu verhindern:

正在加载图表渲染器...

Bei Fehlern werden diese standardmäßig in der Konsole protokolliert und geworfen, es sei denn, suppressErrors ist auf true gesetzt (packages/mermaid/src/mermaid.ts:89-128).

Die initialize()-Funktion

Vor dem Aufruf von run() muss initialize() mit einem Konfigurationsobjekt aufgerufen werden:

javascript
1mermaid.initialize({
2  startOnLoad: true,
3  theme: 'default'
4});

Diese Funktion konfiguriert das Verhalten und Aussehen aller nachfolgenden Diagramme (packages/mermaid/src/mermaid.ts:203-211).

Installation und Einrichtung

Empfohlene Installationsmethode

Die Installation erfolgt über npm als Abhängigkeit im Projekt:

bash
1npm install mermaid

Hinweis: Der genaue Paketname und die Installationsmethode sollten in der package.json oder der offiziellen npm-Seite verifiziert werden (需要确认).

Minimale Einbindung

Nach der Installation kann Mermaid in einer JavaScript- oder TypeScript-Datei importiert und initialisiert werden:

javascript
1import mermaid from 'mermaid';
2
3mermaid.initialize({
4  startOnLoad: true
5});

Die startOnLoad-Konfiguration steuert, ob Diagramme automatisch beim Laden der Seite gerendert werden. Diese Option kann über die Konfiguration aktualisiert werden (packages/mermaid/src/mermaid.ts:149-152).

Alternative Installationsmethoden

MethodeAnwendungsfall
CDN-EinbindungSchnelle Prototypen ohne Build-System
Direct DownloadOffline-Nutzung
Package Manager (yarn/pnpm)Konsistente Versionsverwaltung

Hinweis: Spezifische CDN-URLs und Download-Links müssen in der offiziellen Dokumentation verifiziert werden (需要确认).

Häufige Probleme und Lösungen

Problem 1: Diagramme werden nicht gerendert

Symptome: Der Mermaid-Code wird als Text angezeigt statt als Diagramm.

Lösungsmöglichkeiten:

  • Sicherstellen, dass mermaid.initialize() vor mermaid.run() aufgerufen wird
  • Prüfen, ob der CSS-Selektor .mermaid korrekt ist oder ein benutzerdefinierter Selektor in RunOptions.querySelector angegeben werden muss
  • Überprüfen, ob das data-processed-Attribut bereits gesetzt ist (dies verhindert erneutes Rendering)

Die run()-Funktion überspringt Elemente mit vorhandenem data-processed-Attribut (packages/mermaid/src/mermaid.ts:164-168).

Problem 2: Fehlerbehandlung und Debugging

Symptome: Fehler werden geworfen und brechen die Anwendungsausführung ab.

Lösung: Die Option suppressErrors: true in RunOptions aktivieren, um Fehler nur in der Konsole zu protokollieren:

javascript
1await mermaid.run({
2  suppressErrors: true,
3  querySelector: '.mermaid'
4});

Bei aktivierter Option wird der Fehler geloggt mit dem Hinweis "Use the suppressErrors option to suppress these errors", aber nicht geworfen (packages/mermaid/src/mermaid.ts:123-126).

Problem 3: Veraltete API-Nutzung

Symptome: Warnung "mermaid.init is deprecated. Please use run instead."

Lösung: Die veraltete init()-Funktion durch die Kombination aus initialize() und run() ersetzen:

javascript
1// Veraltet (deprecated)
2// mermaid.init(config, nodes, callback);
3
4// Empfohlen
5mermaid.initialize(config);
6await mermaid.run({
7  postRenderCallback: callback
8});

Die init()-Funktion ist als veraltet markiert und sollte nicht mehr verwendet werden (packages/mermaid/src/mermaid.ts:213-232).

Nächste Schritte

Nach der erfolgreichen Einrichtung von Mermaid empfiehlt sich die Auseinandersetzung mit folgenden Themen:

  1. Diagrammsyntax: Die Diagram Syntax Seite bietet eine umfassende Referenz aller unterstützten Diagrammtypen und deren Syntax.

  2. Konfigurationsoptionen: Die Configuration Reference erklärt detaillierte Anpassungsmöglichkeiten für Themen, Layouts und verhaltensbezogene Einstellungen.

  3. Tutorials: Für praktische Übungen stehen Tutorials zur Verfügung, die schrittweise durch verschiedene Anwendungsfälle führen.

  4. Erweiterte Nutzung: Die Usage Seite dokumentiert fortgeschrittene Integrationsmuster und Best Practices für Produktionsumgebungen.