Deutsche Komposita wie „Rindfleischetikettierungsüberwachungsaufgabenübertragungsgesetz" haben keine Leerzeichen, an denen ein Renderer umbrechen könnte — in einer GFM-Tabelle mit fester Spaltenbreite sprengt so ein einziges Wort mühelos das Layout, während dieselbe Spalte in englischem Text problemlos umbricht.
Grundlegende Syntax
# Überschrift— Überschriften verschiedener Ebenen anhand der Anzahl der#-Zeichen.**fett**und*kursiv*— Textbetonung.[Text](url)— ein Link.- Punktoder1. Punkt— Aufzählungs- und nummerierte Listen.- ``` — Codeblöcke mit Syntaxhervorhebung nach Sprachname.
Warum lange Komposita Markdown-Tabellen sprengen
GFM-Tabellen richten Spalten anhand von Zeichenbreite aus, nicht anhand von Wortgrenzen. Ein zusammengesetztes Substantiv wird als ein einziges „Wort" ohne Leerzeichen behandelt, an dem kein Zeilenumbruch möglich ist — die Spalte wird entweder unlesbar breit oder das Wort läuft über den Zellenrand hinaus. Bei technischer Dokumentation mit deutschen Begriffen lohnt es sich deshalb, Tabellenspalten bewusst kurz zu halten oder auf Bindestrich-Trennung im Wort selbst zurückzugreifen.
Warum es zehn Jahre dauerte, bis es einen echten Standard gab
Das Markdown, das John Gruber 2004 veröffentlichte, war eine Beschreibung in Prosa, keine formale Grammatik, und es definierte weder Tabellen noch durchgestrichenen Text noch Codeblöcke mit Sprachhervorhebung. Ein Jahrzehnt lang legte jede Implementierung die Grauzonen des Originaltexts anders aus, bis CommonMark 2014 eine präzise Grammatik festlegte — und GitHub Flavored Markdown (GFM) darauf aufbauend genau die Tabellen und Task-Listen ergänzte, die heute in praktisch jeder README selbstverständlich wirken.
Umwandlung in HTML und zurück
Die Umwandlung Markdown → HTML ist direkt: Ein Parser erkennt die Syntaxkonstrukte und erzeugt die passenden Tags. Die umgekehrte Umwandlung HTML → Markdown ist schwieriger, da HTML weit mehr Formatierungsmöglichkeiten bietet als das grundlegende Markdown, sodass ein Teil der Auszeichnung (komplexe Tabellen, verschachtelte Stile) vereinfacht oder verloren gehen kann.
Wozu man das braucht
- Schnell eine Vorschau auf das gerenderte Aussehen einer Markdown-Datei bekommen, ohne sie zu veröffentlichen.
- Den Inhalt einer Seite oder eines Dokuments in Markdown umwandeln, um ihn in einer Versionskontrolle zu speichern.
- HTML-Inhalt für eine App vorbereiten, die nur Markdown akzeptiert.