Markdown-Einrückung: Verschachtelte Listen, Absätze und Code
Korrigieren Sie Markdown-Einrückungen anhand von Beispielen für Unterlisten, nummerierte Listen, fortgesetzte Absätze und Codezäune. Vermeiden Sie unbeabsichtigte Codeblöcke.
Um eine Markdown-Unterliste einzurücken, richten Sie ihre Markierung unter dem ersten Zeichen des Textes im übergeordneten Eintrag aus. Bei - Oberpunkt sind das zwei Leerzeichen, bei 1. Oberpunkt drei. Einrückung steuert die Dokumentstruktur. Leerzeichen vor einem normalen Absatz können deshalb eine ganz andere Wirkung haben als das Ändern des sichtbaren Absatzeinzugs in Word.
Beginnen Sie mit diesem Beispiel im Markdown-Viewer:
- Projektdokumente
- Installationsanleitung
- Versionshinweise
- Prüfcheckliste
Installationsanleitung und Versionshinweise sollten unter dem Eintrag für die Projektdokumente erscheinen. Die Prüfcheckliste sollte auf der äußeren Ebene bleiben.
Vom Inhalt des übergeordneten Eintrags aus zählen
Für gewöhnliche Listeneinträge mit einem Leerzeichen nach der Markierung gilt diese Ausrichtung:
| Übergeordneter Eintrag beginnt mit | Zeichen vor seinem Text | Einrückung der Unterliste |
|---|---|---|
- | 2 | 2 Leerzeichen |
1. | 3 | 3 Leerzeichen |
12. | 4 | 4 Leerzeichen |
100. | 5 | 5 Leerzeichen |
Deshalb versagt eine pauschale Regel wie „immer zwei Leerzeichen verwenden“ bei nummerierten Listen. GitHubs Dokumentation zu verschachtelten Listen zeigt die Ausrichtung relativ zum Inhalt des übergeordneten Eintrags, auch bei längeren Zahlenmarkierungen.
1. Die Veröffentlichung vorbereiten
- Die Versionsnummer bestätigen.
- Das Änderungsprotokoll aktualisieren.
2. Die Dokumentation veröffentlichen
Vor den verschachtelten Markierungen stehen drei Leerzeichen. Beginnen sie am linken Rand, bilden sie eine eigene Liste, statt zum ersten nummerierten Schritt zu gehören.
Wenn Sie mit einem älteren Markdown-Prozessor arbeiten, prüfen Sie die Vorschau auch dort. Die Beispiele hier richten sich nach CommonMark-artiger Verarbeitung und GitHub Markdown; ältere Implementierungen erkennen verschachtelte Blöcke möglicherweise anders.
Einen Absatz innerhalb eines Listeneintrags ergänzen
Eine längere Erklärung benötigt keinen eigenen Aufzählungspunkt. Lassen Sie eine Zeile leer und richten Sie den neuen Absatz unter dem Eintragstext aus:
1. Die Installationsanleitung prüfen.
Bestätigen, dass eine neue Person die Einrichtung abschließen kann,
ohne ein internes Dokument zu öffnen.
2. Die Versionshinweise freigeben.
Der erklärende Absatz gehört zu Schritt eins. Seine beiden Quelltextzeilen fließen zusammen, sofern Sie keinen ausdrücklichen Zeilenumbruch einfügen.
Ohne die drei Leerzeichen kann die nummerierte Liste enden und die Erklärung zu einem normalen Absatz werden. In manchen Bearbeitungsabläufen beginnt dadurch auch die Nummerierung der folgenden Liste wieder von vorn.
Dasselbe Muster funktioniert mit Aufzählungen:
- Installationsanleitung
Voraussetzungen, Einrichtungsbefehle und einen Prüfschritt aufnehmen.
- Versionshinweise
Nutzen Sie einen eigenen Absatz, wenn die Erklärung mehrere Sätze enthält. Verwenden Sie eine Unterliste, wenn sie aus verschiedenen Punkten besteht, die Leser einzeln überblicken sollen.
Code innerhalb eines nummerierten Schritts einfügen
Codezäune machen die Grenzen eines Befehlsbeispiels sichtbar. Rücken Sie den öffnenden Codezaun, den Inhalt und den schließenden Codezaun ein, damit der Block innerhalb des Listeneintrags bleibt:
1. Die installierte Version prüfen.
```sh
node --version
```
Das Ergebnis in den Prüfnotizen festhalten.
2. Die Projektprüfungen ausführen.
Hier beginnt der Codezaun unter dem ersten Buchstaben von Die. Der Absatz nach dem Codezaun verwendet dieselbe Ausrichtung und bleibt deshalb ebenfalls innerhalb des ersten Schritts.
Wird der nächste nummerierte Schritt Teil des Codeblocks, prüfen Sie den schließenden Codezaun. Erscheint der Code außerhalb der Liste, prüfen Sie die führenden Leerzeichen des Codezauns. Die Anleitung zu Codeblöcken behandelt Sprachbezeichnungen und wörtliche Backticks.
Warum vier Leerzeichen Text in Code verwandeln können
Auf der äußeren Dokumentebene können vier Leerzeichen vor einer Zeile nach einer Leerzeile einen eingerückten Codeblock erzeugen:
Ein gewöhnlicher Absatz.
Diese Zeile wird als Code angezeigt.
Das ist beabsichtigte Markdown-Syntax und kein defektes Einrückungswerkzeug. Die CommonMark-Referenz zu eingerückten Codeblöcken erklärt die Bedeutung von Einrückung und Blockgrenzen.
Für eine eingerückte Zeile unmittelbar nach gewöhnlichem Absatztext gelten andere Verarbeitungsbedingungen. Leerzeichen sind daher kein zuverlässiges Mittel, um einen sichtbaren Absatzeinzug zu erzeugen. Innerhalb von Listen hängen die erforderlichen Leerzeichen außerdem vom umgebenden Eintrag ab.
Verwenden Sie für ein Zitat ein Blockzitat. Soll gewöhnlicher Fließtext im fertigen Bericht einen Erstzeileneinzug erhalten, belassen Sie ihn in Markdown als normalen Absatz und wenden Sie die Absatzformatierung nach dem Export in Word an. So bleibt die beabsichtigte Bedeutung des Inhalts erhalten.
Bei der Fehlersuche Leerzeichen bevorzugen
Tabulatoren können mehrere Anzeigespalten belegen, und verschiedene Editoren zeigen sie möglicherweise unterschiedlich breit an. Sieht eine Liste im Quelltext ausgerichtet aus, wird aber falsch dargestellt, blenden Sie Leerraum im Editor ein und ersetzen Sie führende Tabulatoren durch die erforderliche Zahl an Leerzeichen.
Ersetzen Sie Tabulatoren innerhalb von Codebeispielen nicht wahllos. Dort kann der Leerraum zum Beispiel selbst gehören. Beschränken Sie die Bereinigung auf Markdown-Markierungen und die Einrückung von Fortsetzungen, die die umgebende Listenstruktur festlegen.
Vermeiden Sie wiederholte Entitäten für geschützte Leerzeichen, um eine verschachtelte Liste nachzuahmen. Dadurch wirkt Text in einer Vorschau möglicherweise verschoben, während das zugrunde liegende Dokument weiterhin aus unverbundenen Absätzen besteht.
Die Struktur vor dem Word-Export prüfen
Prüfen Sie einen repräsentativen Abschnitt mit einem übergeordneten Eintrag, einer Unterliste, einem zweiten Absatz und einem durch Codezäune begrenzten Codeblock. Im Markdown-zu-HTML-Konverter befindet sich eine echte verschachtelte Liste innerhalb ihres übergeordneten Listeneintrags; ein sichtbarer Versatz allein stellt diese Beziehung nicht her.
Verwenden Sie anschließend den Markdown-zu-Word-Konverter und öffnen Sie die DOCX-Datei. Prüfen Sie, ob die Nummerierung wie vorgesehen fortgesetzt wird und Befehle ihren Schritten zugeordnet bleiben. Die Listenformatvorlagen von Word können andere sichtbare Abstände als der Browser verwenden. Beurteilen Sie deshalb vor dem Teilen sowohl die Hierarchie als auch das Erscheinungsbild des fertigen Dokuments.