MDX als Inhaltsformat: Text, der Komponenten kennt

Als die Seite stand, war die nächste Frage, in welchem Format die Inhalte liegen. Reines Markdown ist wunderbar für Text und stößt schnell an Grenzen, sobald man mehr will als Überschriften, Absätze und Listen.

Ich bin bei MDX gelandet: Markdown, das Komponenten kennt. Nach zwei Jahren Erfahrung damit ist mein Urteil differenziert — und genau darum geht es hier.

Was MDX kann

Der Kern ist simpel. Man schreibt Markdown, und an beliebigen Stellen kann man Bausteine einsetzen:

Normaler Text mit **Hervorhebung**.
 
<Warnung>
Das hier ist eine Komponente mit eigenem Aussehen.
</Warnung>
 
Weiter im Text.

Dazu kommt alles, was das Markdown-Ökosystem an Erweiterungen hat: Tabellen, Aufgabenlisten, Fußnoten, automatische Überschriften-Anker, Codeblöcke mit Syntaxhervorhebung.

Für einen technischen Blog ist besonders der letzte Punkt wichtig. Ein Codeblock, der nach Sprache eingefärbt ist und in dem einzelne Zeilen hervorgehoben werden können, macht einen erheblichen Unterschied für die Lesbarkeit.

Die Bausteine, die ich tatsächlich benutze

Nach zwei Jahren sind es genau vier, und das ist eine bewusste Beschränkung:

Hinweis für Zusatzinformationen, die den Lesefluss nicht unterbrechen sollen. Warnung für Dinge, die schiefgehen können. Tipp für praktische Empfehlungen. Und Badge für kleine Markierungen im Text.

Jeder weitere Baustein ist eine Verlockung, aus einem Text eine Anwendung zu machen. Ich habe eine Zeit lang mit eingebetteten interaktiven Beispielen experimentiert und sie wieder entfernt: Sie brauchten Pflege, funktionierten in Vorschauen nicht, und der Erkenntnisgewinn war klein.

Der Kniff mit den Direktiven

Was mir lange gefehlt hat: JSX-Bausteine im Text sehen nicht nach Text aus. Ein <Warnung> mitten in einem Absatz bricht den Schreibfluss und sieht in jedem Editor nach Code aus.

Die elegantere Variante sind Direktiven — eine Markdown-Erweiterung mit einer Syntax, die zum Rest passt:

:::warnung
Der Text der Warnung, ganz normal geschrieben.
:::

Eine Umwandlung beim Verarbeiten macht daraus die entsprechende Komponente. Der Vorteil: Die Quelldatei bleibt lesbar, auch wenn man sie ohne Verarbeitung ansieht — und wenn ich das System einmal wechsle, sind das ein paar Zeilen Umwandlung statt hunderter JSX-Vorkommen.

Wo es unangenehm wird

Ein Syntaxfehler bricht die Seite. Das ist der größte Unterschied zu reinem Markdown. Dort ist eine kaputte Zeile einfach eine hässliche Zeile. In MDX ist eine falsch gesetzte geschweifte Klammer ein Fehler beim Übersetzen — und wenn die Verarbeitung zur Laufzeit passiert, wird daraus eine Fehlerseite.

Deshalb gehört zu jedem Inhaltssystem, das MDX benutzt, eine Prüfung. Bei mir läuft ein Skript, das jede Quelldatei einmal übersetzt und meldet, wenn etwas nicht durchläuft.

Sonderzeichen brauchen Aufmerksamkeit. Geschweifte Klammern werden als Ausdruck gelesen. Spitze Klammern als Element. Wer über Dateiformate schreibt und {"name": "wert"} mitten in einen Absatz setzt, bekommt einen Fehler. Innerhalb von Codeblöcken ist alles harmlos — außerhalb muss man aufpassen.

Warnung

Das ist der Punkt, an dem MDX für rein textliche Inhalte die falsche Wahl sein kann. Wer nur Text schreibt und keine Komponenten braucht, hat mit reinem Markdown weniger Reibung und keine Möglichkeit, die Seite kaputtzumachen. Die Frage lautet ehrlich: Brauche ich Bausteine im Text oft genug, um dieses Risiko zu rechtfertigen?

Suche und Verarbeitung werden komplizierter. Ein Volltextindex über MDX enthält Komponentennamen und Attribute, wenn man nicht aufpasst. Für die Suche muss man das Ergebnis nach der Umwandlung indizieren, nicht die Quelle.

Die Prüfung, die dazugehört

Weil ein Syntaxfehler in einem Beitrag eine Seite unbrauchbar macht, gehört zu diesem Format zwingend eine Kontrolle. Bei mir läuft sie an zwei Stellen.

Beim Speichern. Der Text wird testweise übersetzt, bevor er in die Datenbank geht. Schlägt das fehl, wird nicht gespeichert, und die Meldung sagt, in welcher Zeile das Problem steckt.

Als Durchlauf über alle Inhalte. Ein Skript, das jeden Beitrag einmal übersetzt und meldet, was nicht durchläuft. Das brauche ich, weil sich die Verarbeitung ändern kann — eine neue Fassung einer Erweiterung kann etwas ablehnen, was vorher durchging.

Der zweite Punkt hat mich einmal davor bewahrt, eine Änderung auszuliefern, nach der drei ältere Beiträge nicht mehr dargestellt worden wären.

Die Zeichen, auf die man achten muss

Für alle, die mit diesem Format schreiben — das sind die Fälle, die bei mir tatsächlich zu Fehlern geführt haben:

Geschweifte Klammern im Fließtext. Werden als Ausdruck gelesen. Lösung: in Code-Auszeichnung setzen.

Spitze Klammern im Fließtext. Werden als Element gelesen. Ein Platzhalter wie „Servername in spitzen Klammern" bricht die Verarbeitung, wenn er nicht ausgezeichnet ist.

Zeilen, die mit einem Sonderzeichen beginnen. Manche Kombinationen werden als Auszeichnung gelesen, auch wenn sie als Text gemeint sind.

Leerzeilen um eingebettete Blöcke. Fehlen sie, wird der Block Teil des umgebenden Absatzes und nicht als eigener erkannt.

Diese vier Fälle decken bei mir praktisch alle Fehler ab — und drei davon betreffen technische Texte besonders, weil dort Klammern und Platzhalter ständig vorkommen. Wer über Dateiformate und Konfigurationen schreibt, stolpert häufiger als jemand, der über Reisen schreibt.

Warum ich Komponenten im Text sparsam einsetze

Es gibt einen Punkt, an dem ein Text aufhört, ein Text zu sein — und der ist schneller erreicht, als es beim Bauen scheint.

Ein Text mit vier Sorten Hinweisboxen liest sich nicht besser als einer mit einer. Er sieht nur bunter aus. Jede zusätzliche Auszeichnung verlangt vom Leser eine Entscheidung darüber, wie wichtig etwas ist.

Interaktive Elemente unterbrechen. Ich hatte eine Zeit lang eingebettete Beispiele, mit denen man etwas ausprobieren konnte. Sie waren aufwendig, mussten gepflegt werden, funktionierten in Vorschauen nicht — und niemand hat sie benutzt.

Was nicht als reiner Text funktioniert, funktioniert meistens gar nicht. Der beste Test für einen Beitrag ist, ihn ohne jede Formatierung zu lesen. Wenn der Inhalt dabei zusammenbricht, tragen ihn die Komponenten — und das ist ein schlechtes Zeichen.

Bei mir sind es deshalb vier Bausteine, seit Jahren dieselben, und drei davon sind Varianten desselben Musters.

Wie ich es heute einsetze

Meine Regel nach zwei Jahren:

Reines Markdown, wo es geht — Dokumentation, Notizen, Wiki-Einträge.
MDX dort, wo Hinweisboxen und formatierte Codebeispiele den Text wirklich besser machen — also im Blog und in technischen Anleitungen.
Nie mehr als eine Handvoll Bausteine, und jeder davon muss ohne Erklärung verständlich sein.

Und, wichtiger als alles andere: Die Inhalte müssen ohne das System lesbar bleiben. Wenn ich in zehn Jahren die Dateien öffne und sie ohne die passende Umgebung nur noch Kauderwelsch sind, war das Format die falsche Wahl. Markdown mit vier Direktiven besteht diesen Test. Eine Datei voller verschachtelter JSX-Bausteine nicht.