GitHub Flavored Markdown vs CommonMark: Welchen sollten Sie als Ziel Ihrer Konvertierung wählen
Wenn Sie den falschen Markdown-Dialekt für das Ziel wählen, ist die Konvertierung technisch erfolgreich, während das Ergebnis still falsch gerendert wird: Tabellen werden zu buchstäblichem Text, Durchstreichungen zeigen ihre Tilden, Checkbox-Listen verlieren ihre Kästchen. Die Lösung kostet nichts – aber nur, wenn Sie vor der Konvertierung die richtige Wahl treffen.
Dieser Leitfaden erklärt, was CommonMark tatsächlich spezifiziert, was GitHub Flavored Markdown darüber hinaus ergänzt, welche Plattformen welche Variante sprechen und wie sich die Wahl in der Praxis auswirkt, wenn ein Konverter zwischen Ihren Word-Entwürfen und ihrem endgültigen Veröffentlichungsziel steht.
CommonMark: eine Spezifikation für den Markdown-Kern
Das klassische Markdown war ein Perl-Skript mit einer Prosabeschreibung, und in den 2010er-Jahren waren sich Dutzende Implementierungen bei grundlegenden Fällen uneinig: Geht eine Liste nach einem eingerückten Absatz weiter, was gilt als Hervorhebung über Zeilenumbrüche hinweg, wann ist eine Zahl gefolgt von einem Punkt eine Liste. Dieselbe Datei wurde fast überall anders gerendert.
CommonMark antwortete mit einer formalen Spezifikation: einer eindeutigen Grammatik für die Kernsyntax von Markdown, Hunderten von Testbeispielen mit je einer korrekten Darstellung und Referenzimplementierungen zum Abgleich. John MacFarlane, der auch pandoc entwickelt, gehörte zu den Autoren, und die Spezifikation setzte sich schnell durch.
Heute ist CommonMark die Basisschicht, auf der fast alles aufbaut. Es enthält bewusst weder Tabellen noch Durchstreichungen; es definiert nur das Fundament, auf dem diese Funktionen stehen – und genau deshalb war überhaupt eine zweite Schicht von Erweiterungen nötig.
Was GFM darüber hinaus ergänzt
GitHub Flavored Markdown, 2017 öffentlich spezifiziert, ist eine strikte Obermenge von CommonMark. Die Ergänzungen sind fünf: mit senkrechten Strichen geschriebene Tabellen, Durchstreichung mit doppelten Tilden, Aufgabenlisten mit Checkboxen, automatische Verlinkung nackter URLs und ein Filter, der bestimmte rohe HTML-Tags an der Ausführung hindert.
Jede Ergänzung zielt auf etwas, das Entwickler ohnehin schon geschrieben haben. Pipe-Tabellen decken Abhängigkeits- und Testmatrizen ab; Aufgabenlisten verwandeln eine README in eine Checkliste; Autolinks ersparen das Einklammern jeder URL in spitze Klammern. Der HTML-Filter ist eine Sicherheitsmaßnahme, die die Tags entfernt, die eingebettetes HTML auf einer Website gefährlich machen, auf der jeder bearbeiten kann.
GitHub rendert Markdown über cmark-gfm, einen Fork der CommonMark-Referenzimplementierung mit diesen Erweiterungen. GitLab und Gitea folgen demselben Grundmuster, weshalb sich GFM auf den großen Code-Plattformen konsistent verhält, statt von Site zu Site zu wechseln.
Wo die einzelnen Varianten zu Hause sind
GFM ist natürlich auf GitHub zu Hause und in den statischen Site-Tools, die es standardmäßig verwenden: Hugo rendert von Anfang an über eine für GFM konfigurierte Engine, und MkDocs aktiviert Tabellen ab Werk. Obsidian akzeptiert alle drei charakteristischen Konstrukte – Pipe-Tabellen, Durchstreichung und Aufgabenlisten – und ergänzt eigene Dialektmerkmale.
Strikte CommonMark-Parser leben in Bibliotheken und Blog-Engines, die bewusst einen kleinen, vorhersehbaren Kern bevorzugen. Pandocs eigenes Standard-Markdown ist ein dritter Dialekt, eine große Obermenge mit Grid-Tabellen, Zitiersyntax und anderen Erweiterungen, die GitHub nicht rendert.
Das macht keine Variante besser als die andere. Die Frage ist nie, welcher Dialekt abstrakt gewinnt, sondern welchen Dialekt Ihr Ziel tatsächlich rendert – und ob die Datei, die Sie gerade erzeugen, innerhalb dieser Grenze bleibt.
Warum Konverter den Unterschied ernst nehmen
Ein Konverter übersetzt nicht nur Syntax, er wählt einen Dialekt für die Ausgabe. Bei Tabellen wird die Wahl am sichtbarsten. Ist das Ziel GitHub und unterstützt der Ausgabedialekt Pipe-Tabellen, kommt eine einfache Tabelle als Tabelle an. Tut er das nicht, kann dieselbe Tabelle auf eine Syntax zurückfallen, die das Ziel ignoriert – und Leser sehen Zeilen aus reinem Text mit senkrechten Strichen darin.
Durchstreichungen und Checkboxen von Aufgabenlisten scheitern genauso, nur leiser: sichtbar gebliebene Tilden im Text, wörtlich gerenderte Checkbox-Klammern. Das Dokument ist nicht wirklich beschädigt, es spricht lediglich eine Sprache, die der Renderer des Lesers nicht kennt.
Deshalb ist das Quellformat auch weniger wichtig, als viele erwarten. Pandoc zerlegt die Eingabe, ob docx oder CSV, in ein abstraktes Dokumentmodell, und die Dialektentscheidung fällt beim Schreiben der Ausgabe. Ein Reader, viele Writer – und der Writer ist das, was Sie kontrollieren.
Die Wahl nach Ziel treffen
Für alles, was auf einer Code-Plattform oder in einem Vault landet, wählen Sie GFM: GitHub-Pull-Requests, GitLab-Wikis, Obsidian-Notizen und Hugo-Sites rendern seine Konstrukte. Für eine Blog-Engine oder Bibliothek, die striktes CommonMark verspricht, wählen Sie reines CommonMark und rechnen Sie damit, dass Tabellen einen HTML- oder Erweiterungs-Fallback brauchen.
Wenn Sie das Ziel nicht kennen, ist GFM die sicherere Vorgabe. Seine vier sichtbaren Ergänzungen sind die am breitesten unterstützten Erweiterungen in der Markdown-Welt, und Plattformen, die eine davon auslassen, degradieren meist elegant, statt rohe Syntax zu zeigen.
Der einzige Fehler, den es zu vermeiden lohnt, ist die Annahme, eine Obermenge sei immer sicher. Eine Datei in pandoc-Markdown mit Grid-Tabellen oder Zitiersyntax sieht in pandoc gut aus und bricht auf GitHub. Den Dialekt des Ziels auszugeben schlägt einen reicheren, den das Ziel nicht parsen kann.
Was der GFM-Schalter bei der Konvertierung ändert
Der Konverter auf dieser Website bietet die Wahl als einen einzigen Schalter an. Mit aktiviertem GFM verwendet die Markdown-Ausgabe Pipe-Tabellen, behält Durchstreichungs- und Aufgabenlistensyntax bei und vermeidet Konstrukte, die GitHub nicht rendert, etwa rohe HTML-Bild-Tags oder Breitenattribute an Links.
Ohne diesen Schalter folgt die Ausgabe pandocs eigener Markdown-Variante: immer noch vollkommen gültig, immer noch lesbar, aber komplexe Tabellen können in Dialekten herauskommen, die GitHub ignoriert, und Funktionen jenseits des CommonMark-Kerns landen nicht garantiert in ihren vertrauten GFM-Formen auf der anderen Seite.
Der Schalter hat außerdem eine stille Wechselwirkung, die man kennen sollte: Bei CSV- und TSV-Eingaben ist das Ergebnis ein Tabellendokument, und der GFM-Modus hält diese Tabelle in der Pipe-Syntax, die GitHub tatsächlich rendert, statt in einer Variante, die es ignoriert.
Der Sonderfall Zeilenumbruch
Zeilenumbrüche sind der Unterschied, der jede andere Wahl überlebt. In CommonMark ist ein einzelner Zeilenumbruch innerhalb eines Absatzes ein weicher Umbruch, der als Leerzeichen gerendert wird; für einen harten Umbruch brauchen Sie zwei Leerzeichen am Zeilenende oder einen Backslash. GFM hält für Dateien an dieser Regel fest.
Die Realität ist unübersichtlicher: GitHub-Kommentare und Issue-Texte behandeln einzelne Zeilenumbrüche als sichtbare Umbrüche, und Obsidian macht das standardmäßig genauso, es sei denn, Sie aktivieren strikte Zeilenumbrüche in den Einstellungen. Ein mitten im Satz umbrochener Absatz rendert also auf GitHub anders als in der README daneben.
Die praktische Regel: Schreiben Sie Absätze als einzelne lange Zeilen, wenn die Ausgabe CommonMark oder GFM ist, und verlassen Sie sich nur dort auf Umbruch-als-Zeilenumbruch, wo die Plattform es ausdrücklich so handhabt. Alles andere an der Dialektwahl lässt sich nachträglich korrigieren; Zeilenumbrüche sind das Problem, das sich im Verborgenen zeigt.