Markdown-Listen meistern: CommonMark- & GitHub Flavored Markdown (GFM) Einrückungsstandards
Die technische Grundlage des Markdown-Listen-Renderings
Markdown hat sich als Standard-Auszeichnungssprache für moderne Software-Dokumentationen, technische Spezifikationen, persönliche Wissensdatenbanken und die Entwicklerkommunikation etabliert. Während einfache Listen (- Eintrag) und nummerierte Listen (1. Eintrag) unkompliziert wirken, bringt das Erstellen tief verschachtelter Dokumentgliederungen erhebliche Formatierungskomplexität mit sich. Verschiedene Markdown-Parser — wie CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown und Pandoc — setzen strenge Regeln bezüglich Aufzählungszeichen, Tabulator-zu-Leerzeichen-Verhältnissen und Einrückungen durch.
Wenn Listen zwischen verschiedenen Texteditoren (wie VS Code, Sublime Text, Xcode, Apple Notes oder Microsoft Word) hin- und herkopiert werden, entstehen schleichende Einrückungsfehler. Ein einziges fehlendes Leerzeichen bei einem Untereintrag führt dazu, dass der Markdown-Compiler einen untergeordneten Knoten als Haupteintrag auf oberster Ebene oder als isolierten Absatz interpretiert. Der Formatter für verschachtelte Listen & Einrückungen von Utiliome beseitigt diese Fehler, indem er den abstrakten Syntaxbaum (AST) Ihres Eingabetextes analysiert und standardisiertes, spezifikationskonformes Markdown neu generiert.
Einrückungsregeln: 2-Leerzeichen- vs. 4-Leerzeichen-Richtlinien
Eine der häufigsten Fragen bei der Erstellung technischer Dokumentationen ist, ob Unterlisten mit 2 oder 4 Leerzeichen pro Hierarchieebene eingerückt werden sollten. Die Wahl hängt vom verwendeten Markdown-Parser ab:
Die 2-Leerzeichen-Einrückungsregel (Standard-GFM & Prettier): In modernen Web-Dokumentationssystemen wie GitHub, Docusaurus, Nextra und Obsidian sind 2 Leerzeichen pro Einrückungsebene der anerkannte Standard. Diese Konvention richtet untergeordnete Inhalte unter dem Textanfang des übergeordneten Eintrags aus:
- Haupt-Eintrag 1 - Verschachtelter Untereintrag 1.1 - Verschachtelter Untereintrag 1.2 - Tief verschachtelter Unter-Untereintrag 1.2.1 - Haupt-Eintrag 2Die 4-Leerzeichen-Einrückungsregel (Strikte CommonMark-Vorgabe & Python-Markdown): Strikte CommonMark-Implementierungen verlangen, dass untergeordnete Blöcke, Code-Snippets und verschachtelte Listen innerhalb nummerierter Listen um 4 Leerzeichen (oder 1 Tabulator) eingerückt werden, um die Zugehörigkeit zum Elternblock zu garantieren:
1. Erster geordneter Schritt im Arbeitsablauf - Zugehöriger Unterpunkt A - Zugehöriger Unterpunkt B 2. Zweiter geordneter Schritt im ArbeitsablaufFallen bei Tabulatoren vs. Leerzeichen: Das Mischen von Tabulatoren (
\t) mit ASCII-Leerzeichen (\x20) ist die Hauptursache für fehlerhaft dargestellte Markdown-Dokumente. Web-Rendering-Engines interpretieren Tabulatoren unterschiedlich (oft als 4 oder 8 Zeichen), was dazu führt, dass verschachtelte Elemente visuell verrutschen. Utiliome wandelt alle Tabulatoren automatisch in einheitliche Leerzeichen um, genau wie von Ihnen konfiguriert.
Aufzählungszeichen vereinheitlichen & Reihenfolgen korrigieren
Markdown unterstützt drei verschiedene Aufzählungszeichen für ungeordnete Listen: Bindestriche (-), Sternchen (*) und Pluszeichen (+). Obwohl alle drei gültige HTML-Elemente (<ul>) erzeugen, führt das Mischen von Zeichen in demselben Dokument zu visueller Unruhe und lässt automatisierte Linter-Prüfungen (wie die MD004-Regel von markdownlint) fehlschlagen.
Darüber hinaus bricht die Nummerierung geordneter Listen bei Überarbeitungen häufig. Autoren fügen oft neue Punkte mitten in bestehende Reihen ein oder verlassen sich auf die automatische Inkrementierung mit 1.:
<!-- Unformatierte / fehlerhafte Eingabe -->
* Funktion A
- Funktion B
+ Funktion C
1. Erster Schritt
1. Zweiter Schritt (aus Entwurf kopiert)
4. Falsch nummerierter Schritt
Der Formatter von Utiliome vereinheitlicht alle Aufzählungszeichen auf Ihr gewünschtes Zeichen (z. B. alle Punkte auf -) und nummeriert geordnete Sequenzen fortlaufend (1., 2., 3.) oder setzt sie auf saubere 1.-Inkremente zurück — ganz nach den Stilrichtlinien Ihres Teams.