Herstellung von Meerjungfrau -Diagrammen in Markdown

Meerjungfrau -Diagramme und Flussdiagramme haben an Traktion gewonnen, insbesondere mit Githubs Ankündigung, dass sie im Markdown nativ unterstützt werden. Schauen wir uns an, was sie sind, wie man sie benutzt, und genauso wichtig: Warum .

Genau wie Sie Ihre Codepen -Demo vielleicht direkt in Ihre Dokumentationsquelle einbetten möchten, hilft Ihre Diagramme und Diagramme, die neben Ihrem Text live live live, verhindert, dass sie verrottet - das heißt, die Synchronisierung mit dem Status Ihres Dokuments zu verdrehen. So wie nicht hilfreiche, 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 Site -Generatoren, die immer beliebter werden. Die Paarung ist natürlich. Während Meerjungfrau-Diagramme nicht ausschließend markieren, sind sie inspiriert. Mit dem gleichen Markup -Abstraktions -Markdown für Notate -Code kann die Meerjungfrau so dargestellt werden, dass Ausgangsdiagramme und Flussdiagramme. Und Markdown ist es, statische Websites zu jamstieren, da Erdnussbutter für Gelee ist.

Wenn Ihre Website in Markdown verfasst, in HTML verarbeitet wird und Sie über genügend Kontrolle verfügen, um ein wenig benutzerdefinierte JavaScript hinzuzufügen, können Sie die Ideen verwenden, die wir in diesem Artikel abdecken, um Ihre eigenen Anforderungen zu entsprechen und Diagramme mit Mermaid bequem neben dem Rest Ihres Markdowns zu implementieren. Ist "Diagramme als Code" schon ein Begriff? Es sollte sein.

Nehmen wir beispielsweise an, Sie arbeiten an einem schicken neuen Produkt und möchten eine Roadmap in Form eines Gantt -Diagramms (oder eines anderen Typs - beispielsweise Flowdiagramme, Sequenzen und Klassendiagramme) anbieten. Mit Meerjungfrau können Sie dies in einer kleinen Handvoll Linien tun:

 Gantt
  Titel meine Produkt Roadmap
  DateFormat yjyy-mm-dd
  Abschnitt coole Funktion
  Eine Aufgabe: A1, 2022-02-25, 30d
  Eine andere Aufgabe: nach A1, 20d
  Abschnitt RAD -Merkmal
  Aufgabe in Sequenz: 2022-03-04, 12d
  Aufgabe, Nr. 2: 24d

Das wird ein schönes SVG -Diagramm wie so machen:

Pro -Tipp: Mermaid hat einen Live -Redakteur, mit dem Sie ihn ohne die Verpflichtung bei mermaid.live ausprobieren können.

Meerjungfrau -Diagramme im Markdown

Mermaid passt gut zu Markdown, da sie sich nur als einen weiteren eingezäunten Codeblock darstellt und nur den Mermaid -Sprachsyntaxsatz verwendet. Zum Beispiel dieser Codeblock:

 `` `mermaid
Graph TD;
    A-> B;
    A-> c;
    B-> d;
    C-> D;
`` `

… Erzeugt ein HTML

 -Element mit dem Code -Block -Inhalt in:<pre rel="HTML" data-line=""> <pre class="brush:php;toolbar:false"> <code> Graph TD;
    A-> B;
    A-> c;
    B-> d;
    C-> d; </code> 

Wenn Sie einen Markdown -Prozessor verwenden, der mit der Commonmark -Spezifikation ausgerichtet ist, ähnelt dies mehr:

 <pre class="brush:php;toolbar:false"> <code> Graph TD;
    A-> B;
    A-> c;
    B-> d;
    C-> D;
</code> 

Demo anzeigen

Das Standardverhalten der Meerjungfrau-API erwartet ein

-Tag, das den Inhalt direkt enthält.

Finising mit JavaScript

Mit ein bisschen JavaScript ist es vernünftig, das von Markdown erzeugte HTML und die Finesse in das

-Tag zu nehmen, das Meerjungfrauenziele. Es ist erwähnenswert, dass $ element.textContent hier zielgerichtet ist: Markdown wird html-codieren spezifische Zeichen (wie> in & gt;), die Meerjungfrau verwendet. Es filtert auch alle fehlerhaften HTML -Elemente, die Nachkommen des

 -Elements sind.<pre rel="JavaScript" data-line=""> // Auswählen <pre class="brush:php;toolbar:false"> _and_ <pre class="brush:php;toolbar:false"> <code>
document.querySelectorAll ("pre.mermaid, pre> code.language-mermaid"). foreach ($ el => {
  // Wenn der zweite Selektor einen Treffer erhalten hat, verweisen Sie auf das übergeordnete <pre class="brush:php;toolbar:false">
  if ($ el.tagname === "Code")
    $ el = $ El.Parentelement
  // Die Meerjungfrauinhalte in die erwartete <div> einlegen
  // Plus den ursprünglichen Inhalt in einem schönen <details> behalten
  $ el.outerhtml = `
    <div> $ {$ el.TextContent} </div>
    <details>
      <summary> Diagrammquelle </summary>
      <pre class="brush:php;toolbar:false"> $ {$ el.TextContent} 

` })

Jetzt, da unsere HTML ordnungsgemäß formatiert ist, lassen Sie die Mermaid implementieren, um das Rendering durchzuführen.

Mit Meerjungfrau

Mermaid wird als NPM-Paket veröffentlicht, sodass Sie eine Kopie mit einem paketbewussten CDN wie UNPKG verwenden können. Sie möchten den Minimified Code (z. B. mermaid.min.js) anstelle des Standard -Exports von mermaid.core.js verwenden. Zum Beispiel:

 <script src="https://unpkg.com/%5Bemail%20Protected%5D%20/dist/mermaid.min.js"> </script>

Die Meerjungfrau ist auch ESM-fähig, sodass Sie mit SkyPack es auch laden können:

 <script type="modul">
  Mermaid importieren "https://cdn.skypack.dev/®email Protected]";
</script>

Sie könnten hier anhalten, wenn Sie die Dinge einfach halten möchten. Standardmäßig initialisiert Mermaid sich automatisch selbst, wenn das Dokument fertig ist. Solange Sie die Markdown-to-HTML-Finising mit JavaScript vor dem Laden vor dem Laden von Meerjungfrau durchführen, werden Sie alle festgelegt.

Mermaid verfügt jedoch über ein paar Einstellungen, die es wert sind, konfiguriert zu werden:

 // Mermaid in [1] Protokollfehler initialisieren, [2] haben eine lose Sicherheit für Erstanbieter
// verfasste Diagramme und [3] respektieren ein bevorzugtes Dark -Farbschema
mermaid.initialize ({{
  Loglevel: "Fehler", // [1]
  SecurityLevel: "lose", // [2]
  Thema: (window.matchmedia && window.matchmedia ("(bevorzugt Farbscheme: dunkel)"). Übereinstimmung)?
    "dunkel" :
    "Standard" // [3]
})

1. Loglevel gibt Ihnen ein bisschen mehr Sichtbarkeit in alle Fehler, die auftreten können. Wenn Sie weitere Informationen anzeigen möchten, können Sie eine ausführlichere Ebene auswählen (oder umgekehrt).
2. SecurityLevel bezieht sich auf das Vertrauensniveau für die Diagrammquelle. Wenn Sie sich zufrieden stellen, ist "locker" in Ordnung. Wenn es sich um benutzergenerierte Inhalte handelt, ist es wahrscheinlich am besten, den "strengen" Standard zu verlassen.
3. Das Thema verändert das Styling der gerenderten Diagramme. Durch Abfragen des bevorzugten Farbschemas und der Nutzung eines ternären Operators können wir gegebenenfalls "dunkel" angeben.

Alles zusammen jetzt!

Hier sind einige Beispiele für Meerjungfrau -Diagramme in Markdown:

Tieferes Wasser

Diese Strategie ist besonders effektiv, da sie progressiv ist : Wenn JavaScript deaktiviert ist, wird die ursprüngliche Meerjungfrauquelle as-is angezeigt. Kein Foul.

Es gibt auch eine vollwertige Befehlszeilenschnittstelle für Meerjungfrau, die, wenn Sie interessant zum Erkunden sind, möglicherweise genutzt werden können, um Diagramme anzuzeigen, die vollständig serverseitig gerendert werden. Zwischen der Mermaid -CLI und dem Online -Generator kann es sogar möglich sein, sich in den Erstellungsvorgang einzuschließen, den Sie verwenden, um einen Schnappschuss eines Diagramms zu erstellen und es als -Fallback anstelle des Quellcode zu anzeigen.

Hoffentlich sehen wir mehr native Mermaid -Integrationen wie diese, da die Meerjungfrau immer beliebter wird. Die Nützlichkeit von visuellen Diagrammen und Diagrammen sowie Dokumentation ist unbestreitbar - von Produkt -Roadmaps bis hin zu Entscheidungsbäumen und allem dazwischen. Das ist die Art von Informationen, die einfach nur schwer mit Wörtern zu dokumentieren sind.

Mermaid -Diagramme lösen dies und so, dass die Informationen neben dem Rest der Dokumentation verwaltet und verwaltet werden können.