Mermaid-Diagramme in Markdown erstellen

Mermaid Diagramme und Flussdiagramme gewinnen an Beliebtheit, insbesondere seit GitHubs Ankündigung, dass sie nativ in Markdown unterstützt werden. Schauen wir uns an, was sie sind, wie man sie benutzt und – was ebenso wichtig ist: *warum*.

So wie Sie vielleicht Ihre CodePen-Demos direkt in Ihrem Dokumentationsquelltext einbetten möchten, hilft es, wenn Ihre Diagramme und Grafiken direkt neben Ihrem Text stehen, damit sie nicht „veralten“ – das heißt, aus dem Gleichgewicht mit dem Zustand Ihres Dokuments geraten. So wie unhilfreiche, veraltete oder anderweitig irreführende Kommentare in Ihrem Code objektiv schlechter sein können als *keine* Kommentare, gilt das Gleiche für Diagramme.

Mermaid-Diagramme passen gut zu Jamstack und statischen Website-Generatoren, die immer beliebter werden. Die Kombination ist natürlich. Obwohl Mermaid-Diagramme nicht exklusiv für Markdown sind, sind sie von Markdown inspiriert. Unter Verwendung derselben Markup-Abstraktionen, die Markdown zur Notation von Code bereitstellt, kann Mermaid so dargestellt werden, dass es Diagramme und Flussdiagramme ausgibt. Und Markdown ist für Jamstack und statische Websites wie Erdnussbutter für Marmelade.

Wenn Ihre Website in Markdown verfasst, in HTML verarbeitet wird und Sie genügend Kontrolle haben, um ein wenig benutzerdefiniertes JavaScript hinzuzufügen, können Sie die in diesem Artikel behandelten Ideen nutzen, um Ihre eigenen Bedürfnisse zu erfüllen und Diagramme mit Mermaid bequem neben dem Rest Ihres Markdowns zu implementieren. Ist „Diagramme-als-Code“ schon ein Begriff? Das sollte es sein.

Nehmen wir zum Beispiel an, Sie arbeiten an einem schicken neuen Produkt und möchten eine Roadmap in Form eines Gantt-Diagramms (oder eines anderen Typs – z. B. Flussdiagramme, Sequenzen und Klassendiagramme) bereitstellen. Mit Mermaid können Sie dies in wenigen Zeilen tun

gantt
  title My Product Roadmap
  dateFormat  YYYY-MM-DD
  section Cool Feature
  A task           :a1, 2022-02-25, 30d
  Another task     :after a1, 20d
  section Rad Feature
  Task in sequence :2022-03-04, 12d
  Task, No. 2      :24d

Was ein schönes SVG-Diagramm wie folgt rendert

Pro-Tipp: Mermaid verfügt über einen Live-Editor, mit dem Sie es ohne Verpflichtung ausprobieren können unter mermaid.live.

Mermaid-Diagramme in Markdown

Mermaid passt gut zu Markdown, da es sich als nur ein weiteres eingezäuntes Codeblock präsentiert, das die mermaid-Sprachsyntax verwendet. Zum Beispiel dieser Codeblock

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

… erzeugt ein HTML <pre>-Element mit dem Inhalt des Codeblocks darin

<pre class="mermaid"><code>graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;</code></pre>

Wenn Sie einen Markdown-Prozessor verwenden, der mit der CommonMark-Spezifikation übereinstimmt, wird es eher so aussehen

<pre><code class="language-mermaid">graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</code></pre>

Das Standardverhalten der Mermaid-API erwartet einen <div class="mermaid">-Tag, der direkt den Inhalt enthält – also kein <code> oder <span> (wie von einem Syntax-Hervorheber), das Sie möglicherweise bei der Konvertierung von Markdown zu HTML sehen.

Verfeinerung mit JavaScript

Mit ein wenig JavaScript ist es sinnvoll, das von Markdown generierte HTML zu nehmen und es in den <div class="mermaid">-Tag zu verfeinern, den Mermaid anvisiert. Es ist erwähnenswert, dass $element.textContent hier zweckmäßig ist: Markdown wird bestimmte Zeichen (wie > in >) HTML-codieren, die Mermaid verwendet. Außerdem werden alle fehlerhaften HTML-Elemente gefiltert, die Nachkommen des <pre>-Elements sind.

// select <pre class="mermaid"> _and_ <pre><code class="language-mermaid">
document.querySelectorAll("pre.mermaid, pre>code.language-mermaid").forEach($el => {
  // if the second selector got a hit, reference the parent <pre>
  if ($el.tagName === "CODE")
    $el = $el.parentElement
  // put the Mermaid contents in the expected <div class="mermaid">
  // plus keep the original contents in a nice <details>
  $el.outerHTML = `
    <div class="mermaid">${$el.textContent}</div>
    <details>
      <summary>Diagram source</summary>
      <pre>${$el.textContent}</pre>
    </details>
  `
})

Nachdem unser HTML richtig formatiert ist, implementieren wir Mermaid für das Rendering.

Mermaid verwenden

Mermaid wird als npm-Paket veröffentlicht, sodass Sie eine Kopie erhalten können, indem Sie einen paketabhängigen CDN wie unpkg verwenden. Sie sollten den minifizierten Code (z. B. mermaid.min.js) anstelle des Standardexports von mermaid.core.js verwenden. Zum Beispiel

<script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>

Mermaid ist *auch* ESM-fähig, sodass Sie Skypack verwenden können, um es ebenfalls zu laden

<script type="module">
  import mermaid from "https://cdn.skypack.dev/[email protected]";
</script>

Sie könnten hier aufhören, wenn Sie die Dinge einfach halten möchten. Standardmäßig initialisiert sich Mermaid automatisch, wenn das Dokument bereit ist. Solange Sie die Markdown-zu-HTML-Verfeinerung mit JavaScript durchführen, die wir zuvor erwähnt haben – *bevor* Sie Mermaid laden – sind Sie bestens gerüstet.

Mermaid hat jedoch ein paar konfigurierbare Einstellungen, die sich lohnen

// initialize Mermaid to [1] log errors, [2] have loose security for first-party
// authored diagrams, and [3] respect a preferred dark color scheme
mermaid.initialize({
  logLevel: "error", // [1]
  securityLevel: "loose", // [2]
  theme: (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) ?
    "dark" :
    "default" // [3]
})

1. logLevel gibt Ihnen mehr Einblick in mögliche Fehler. Wenn Sie mehr Informationen sehen möchten, können Sie eine ausführlichere Stufe wählen (oder umgekehrt).
2. securityLevel bezieht sich auf die Vertrauensstufe für die Diagrammquelle. Wenn es sich um von Ihnen erstellte Inhalte handelt, ist "loose" in Ordnung. Wenn es sich um benutzergenerierte Inhalte handelt, ist es wahrscheinlich am besten, den Standardwert "strict" beizubehalten.
3. theme ändert die Gestaltung der gerenderten Diagramme. Indem wir die bevorzugte Farbschema-Abfrage abfragen und einen ternären Operator verwenden, können wir entsprechend "dark" angeben.

Alles zusammen jetzt!

Hier sind ein paar Beispiele für Mermaid-Diagramme in Markdown

Tiefere Gewässer

Diese Strategie ist besonders effektiv, weil sie *progressiv* ist: Wenn JavaScript deaktiviert ist, wird die ursprüngliche Mermaid-Quelle unverändert angezeigt. Kein Problem.

Es gibt auch ein voll ausgestattetes Kommandozeileninterface für Mermaid, das, wenn Sie daran interessiert sind, es zu erkunden, potenziell genutzt werden könnte, um Diagramme anzuzeigen, die vollständig serverseitig gerendert sind. Zwischen der Mermaid CLI und dem Online-Generator ist es vielleicht sogar möglich, sich in Ihren Build-Prozess einzuhaken, um einen Schnappschuss eines Diagramms zu generieren und ihn als <img>-Fallback anstelle des Quellcodes anzuzeigen.

Hoffentlich werden wir mehr native Mermaid-Integrationen wie diese sehen, da Mermaid immer beliebter wird. Der Nutzen, visuelle Grafiken und Diagramme neben Dokumentationen zu haben, ist unbestreitbar – von Produkt-Roadmaps bis hin zu Entscheidungsbäumen und allem dazwischen. Das sind Informationen, die sich mit Worten allein nur schwer dokumentieren lassen.

Mermaid-Diagramme lösen dieses Problem und auf eine Weise, die sicherstellt, dass die Informationen neben dem Rest der Dokumentation verwaltet und gepflegt werden können.