Verwendung

Mermaid ist ein JavaScript-Tool, das eine auf Markdown basierende Syntax verwendet, um anpassbare Diagramme, Grafiken und Visualisierungen darzustellen.

Diagramme können neu gerendert/modifiziert werden, indem ihre Beschreibungen geändert werden.

CDN

https://www.jsdelivr.com/package/npm/mermaid

Bitte beachten Sie, dass Sie die Versionen über das Dropdown-Feld in der oberen rechten Ecke wechseln können.

Verwendung von mermaid

Für die Mehrheit der Benutzer wäre die Verwendung des Live Editors ausreichend, Sie können jedoch auch entscheiden, mermaid als Abhängigkeit einzusetzen oder die Mermaid API zu verwenden.

Wir haben einige Video-Tutorials zusammengestellt, wie man den Mermaid Live Editor benutzt.

Installation und Hosting von Mermaid auf einer Webseite

Verwendung des npm-Pakets:

Anforderungen:

Node >= 16

bash

# NPM
npm install mermaid
# Yarn
yarn add mermaid
# PNPM
pnpm add mermaid

Hosting von mermaid auf einer Webseite:

Hinweis: Dieses Thema wird im Benutzerhandbuch für Anfänger ausführlicher behandelt.

Der einfachste Weg, mermaid auf einer Webseite zu integrieren, erfordert zwei Elemente:

Eine Diagrammdefinition, die sich innerhalb von <pre>-Tags befindet, die mit class=mermaid gekennzeichnet sind.

Beispiel:

html

<pre class="mermaid">
    graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
</pre>

Das Mermaid-JS-Skript. Hinzugefügt über ein script-Tag als ESM-Import.

Beispiel:

html

<script type="module">
  import mermaid from '<CDN_URL>/mermaid@<MERMAID_VERSION>/dist/mermaid.esm.min.mjs';
</script>

Wenn Sie diese Anweisungen befolgen, startet mermaid beim Laden der Seite und (wenn die Seite geladen ist) wird es die Diagrammdefinitionen in den pre-Tags mit class="mermaid" finden und Diagramme in SVG-Form zurückgeben, gemäß den gegebenen Definitionen.

Einfaches Vollbeispiel:

html

<!doctype html>
<html lang="de">
  <body>
    <pre class="mermaid">
  graph LR
      A --- B
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
    </pre>
    <script type="module">
      import mermaid from '<CDN_URL>/mermaid@<MERMAID_VERSION>/dist/mermaid.esm.min.mjs';
    </script>
  </body>
</html>

Hinweise:

Ein id-Attribut wird auch zu mermaid-Tags ohne ein solches hinzugefügt.

Mermaid kann mehrere Diagramme auf derselben Seite laden.

Probieren Sie es aus, speichern Sie diesen Code als HTML und laden Sie ihn mit einem beliebigen Browser. (Außer Internet Explorer, bitte verwenden Sie keinen Internet Explorer.)

Aktivierung von Klickereignissen und Tags in Knoten

Eine Konfiguration von securityLevel muss zuerst genehmigt werden. securityLevel legt das Vertrauensniveau für die geparsten Diagramme fest und limitiert die Klickfunktionalität. Dies wurde in Version 8.2 als Sicherheitsverbesserung eingeführt, um böswillige Verwendung zu verhindern.

Es liegt in der Verantwortung des Site-Betreibers, zwischen vertrauenswürdigen und nicht vertrauenswürdigen Benutzergruppen zu unterscheiden, und wir empfehlen den Einsatz von Diskretion.

securityLevel

Parameter	Beschreibung	Typ	Erforderlich	Werte
securityLevel	Vertrauensniveau für geparstes Diagramm	String	Optional	'sandbox', 'strict', 'loose', 'antiscript'

Werte:

strict: (Standard) HTML-Tags im Text werden kodiert und die Klickfunktionalität ist deaktiviert.
antiscript: HTML-Tags im Text sind erlaubt (nur Script-Elemente werden entfernt) und die Klickfunktionalität ist aktiviert.
loose: HTML-Tags im Text sind erlaubt und die Klickfunktionalität ist aktiviert.
sandbox: Mit diesem Sicherheitslevel erfolgt das Rendering in einem sandboxed iframe. Dies verhindert, dass JavaScript im Kontext ausgeführt wird. Dies kann die interaktive Funktionalität des Diagramms beeinträchtigen, wie Skripte, Popups im Sequenzdiagramm, Links zu anderen Tabs oder Zielen usw.

NOTE

Dies ändert das Standardverhalten von mermaid, sodass nach dem Upgrade auf 8.2, sofern das `securityLevel` nicht geändert wird, die Tags in Flussdiagrammen als Tags kodiert und das Klicken deaktiviert wird. **sandbox** Sicherheitslevel befindet sich noch in der Beta-Version.

Wenn Sie für die Sicherheit der Diagrammquelle verantwortlich sind, können Sie securityLevel auf einen Wert Ihrer Wahl setzen. Dies erlaubt Klicks und Tags sind erlaubt.

Um securityLevel zu ändern, müssen Sie mermaid.initialize aufrufen:

javascript

mermaid.initialize({
  securityLevel: 'loose',
});

Labels außerhalb der Grenzen

Wenn Sie dynamisch geladene Schriftarten verwenden, die über CSS geladen werden, wie Schriftarten, sollte mermaid warten, bis die gesamte Seite geladen ist (DOM + Assets, insbesondere die Schriftartdatei).

javascript

$(document).ready(function () {
  mermaid.initialize();
});

Andernfalls führt dies wahrscheinlich dazu, dass mermaid Grafiken rendert, die Labels außerhalb der Grenzen haben. Die Standardintegration in mermaid verwendet das window.load-Ereignis, um mit dem Rendern zu beginnen.

Wenn Ihre Seite andere Schriftarten im Body hat, könnten diese anstelle der mermaid-Schriftart verwendet werden. Die Angabe der Schriftart in Ihrem Styling ist eine Lösung dafür.

css

pre.mermaid {
  font-family: 'trebuchet ms', verdana, arial;
}

Verwendung von `mermaid.run`

mermaid.run wurde in v10 hinzugefügt und ist der bevorzugte Weg zur Handhabung komplexerer Integrationen. Standardmäßig wird mermaid.run aufgerufen, wenn das Dokument bereit ist, wobei alle Elemente mit class="mermaid" gerendert werden.

Sie können dieses Verhalten anpassen, indem Sie await mermaid.run(<config>) aufrufen.

mermaid.initialize({startOnLoad: false}) verhindert, dass mermaid.run automatisch nach dem Laden aufgerufen wird.

Rendert alle Elemente mit querySelector ".someOtherClass"

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  querySelector: '.someOtherClass',
});

Rendert alle Elemente, die als Array übergeben werden

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  nodes: [document.getElementById('someId'), document.getElementById('anotherId')],
});
await mermaid.run({
  nodes: document.querySelectorAll('.yetAnotherClass'),
});

Rendert alle .mermaid-Elemente, während Fehler unterdrückt werden

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  suppressErrors: true,
});

Aufruf von `mermaid.init` - Veraltet

WARNING

mermaid.init ist in v10 veraltet und wird in einer zukünftigen Veröffentlichung entfernt. Bitte verwenden Sie stattdessen mermaid.run.

Standardmäßig wird mermaid.init aufgerufen, wenn das Dokument bereit ist, und alle Elemente mit class="mermaid" gefunden werden. Wenn Sie Inhalte nach dem Laden von mermaid hinzufügen oder anderweitig eine spezifischere Kontrolle über dieses Verhalten benötigen, können Sie init selbst mit:

einem Konfigurationsobjekt
einigen Knoten aufrufen, als
- einen Knoten
- ein arrayähnliches von Knoten
- oder einen W3C-Selektor, der Ihre Knoten findet

Beispiel:

javascript

mermaid.init({ noteMargin: 10 }, '.someOtherClass');

Oder ohne Konfigurationsobjekt und mit einer jQuery-Auswahl:

javascript

mermaid.init(undefined, $('#someId .yetAnotherClass'));

Verwendung mit webpack

mermaid unterstützt vollständig webpack. Hier ist eine funktionierende Demo.

API-Nutzung

Die Hauptidee der API besteht darin, eine Renderfunktion mit der Diagrammdefinition als Zeichenfolge aufzurufen. Die Renderfunktion rendert das Diagramm und ruft einen Callback mit dem resultierenden SVG-Code auf. Mit diesem Ansatz liegt es am Seitenbetreiber, die Diagrammdefinition von der Seite abzurufen (vielleicht aus einem Textbereich), es zu rendern und das Diagramm irgendwo auf der Seite zu platzieren.

Das Beispiel unten zeigt, wie dies verwendet werden könnte. Das Beispiel protokolliert lediglich das resultierende SVG in die JavaScript-Konsole.

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  mermaid.initialize({ startOnLoad: false });

  // Beispiel für die Verwendung der Renderfunktion
  const drawDiagram = async function () {
    element = document.querySelector('#graphDiv');
    const graphDefinition = 'graph TB\na-->b';
    const { svg } = await mermaid.render('graphDiv', graphDefinition);
    element.innerHTML = svg;
  };

  await drawDiagram();
</script>

Um den Typ des Diagramms in einem gegebenen Text zu bestimmen, können Sie die Funktion mermaid.detectType nutzen, wie im folgenden Beispiel gezeigt.

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  const graphDefinition = `sequenceDiagram
    Pumbaa->>Timon:I ate like a pig.
    Timon->>Pumbaa:Pumbaa, you ARE a pig.`;
  try {
    const type = mermaid.detectType(graphDefinition);
    console.log(type); // 'sequence'
  } catch (error) {
    // UnknownDiagramError
  }
</script>

Ereignisse binden

Manchmal hat das generierte Diagramm auch definierte Interaktionen wie Tooltips und Klickereignisse. Bei der Verwendung der API muss man diese Ereignisse hinzufügen, nachdem das Diagramm in den DOM eingefügt wurde.

Der Beispielcode unten ist ein Ausschnitt dessen, was mermaid bei der Verwendung der API tut. Das Beispiel zeigt, wie es möglich ist, Ereignisse zu bindet, wenn man die API zum Rendern verwendet.

javascript

// Beispiel für die Verwendung der bindFunctions
const drawDiagram = async function () {
  element = document.querySelector('#graphDiv');
  const graphDefinition = 'graph TB\na-->b';
  const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);
  element.innerHTML = svg;
  // Das kann auch so geschrieben werden: `bindFunctions?.(element);` unter Verwendung des `?`-Abkürzung.
  if (bindFunctions) {
    bindFunctions(element);
  }
};

Das Diagramm wird mit dem Renderaufruf generiert.
Nach der Generierung ruft die Renderfunktion die bereitgestellte Callback-Funktion auf, in diesem Fall wird sie insertSvg genannt.
Die Callback-Funktion wird mit zwei Parametern aufgerufen, dem SVG-Code des generierten Diagramms und einer Funktion. Diese Funktion bindet Ereignisse an das SVG nachdem es in den DOM eingefügt wurde.
Fügen Sie den SVG-Code in den DOM zur Anzeige ein.
Rufen Sie die Bindefunktion auf, die die Ereignisse bindet.

Beispiel eines markierten Renderers

Dies ist der Renderer, der verwendet wird, um die Dokumentation von Markdown nach HTML mit mermaid-Diagrammen im HTML zutransformieren.

javascript

const renderer = new marked.Renderer();
renderer.code = function (code, language) {
  if (code.match(/^sequenceDiagram/) || code.match(/^graph/)) {
    return '<pre class="mermaid">' + code + '</pre>';
  } else {
    return '<pre><code>' + code + '</code></pre>';
  }
};

Ein weiteres Beispiel in CoffeeScript, das auch das mermaid-Skript-Tag in den generierten Markup einfügt.

coffee

marked = require 'marked'

module.exports = (options) ->
  hasMermaid = false
  renderer = new marked.Renderer()
  renderer.defaultCode = renderer.code
  renderer.code = (code, language) ->
    if language is 'mermaid'
      html = ''
      if not hasMermaid
        hasMermaid = true
        html += '<script src="'+options.mermaidPath+'"></script>'
      html + '<pre class="mermaid">'+code+'</pre>'
    else
      @defaultCode(code, language)

  renderer

Erweiterte Verwendung

Syntaxvalidierung ohne Rendering

Die Funktion mermaid.parse(text, parseOptions) validiert Diagrammdefinitionen, ohne ein Diagramm zu rendern.

Die Funktion mermaid.parse(text, parseOptions) nimmt eine Textzeichenfolge als Argument und gibt { diagramType: string } zurück, wenn die Definition mermaids Syntax entspricht.

Wenn die Definition ungültig ist, gibt die Funktion false zurück, wenn parseOptions.suppressErrors auf true gesetzt ist. Andernfalls wird ein Fehler ausgelöst.

Die parseError-Funktion wird aufgerufen, wenn die parse-Funktion einen Fehler auslöst. Sie wird nicht aufgerufen, wenn parseOptions.suppressErrors auf true gesetzt ist.

Es ist möglich, diese Funktion zu überschreiben, um den Fehler auf anwendungsspezifische Weise zu behandeln.

Der Code-Auss

Verwendung ​

CDN ​

Verwendung von mermaid ​

Installation und Hosting von Mermaid auf einer Webseite ​

Einfaches Vollbeispiel: ​

Hinweise: ​

Aktivierung von Klickereignissen und Tags in Knoten ​

securityLevel ​

Labels außerhalb der Grenzen ​

Verwendung von mermaid.run ​

Aufruf von mermaid.init - Veraltet ​

Verwendung mit webpack ​

API-Nutzung ​

Ereignisse binden ​

Beispiel eines markierten Renderers ​

Erweiterte Verwendung ​

Syntaxvalidierung ohne Rendering ​

Verwendung

CDN

Verwendung von mermaid

Installation und Hosting von Mermaid auf einer Webseite

Einfaches Vollbeispiel:

Hinweise:

Aktivierung von Klickereignissen und Tags in Knoten

securityLevel

Labels außerhalb der Grenzen

Verwendung von `mermaid.run`

Aufruf von `mermaid.init` - Veraltet

Verwendung mit webpack

API-Nutzung

Ereignisse binden

Beispiel eines markierten Renderers

Erweiterte Verwendung

Syntaxvalidierung ohne Rendering