Was ist Markdown? Syntax, CommonMark und GFM

Denken Sie an die README eines Softwareprojekts, an Listen mit Überschriften in einer Notiz-App oder an Wörter, die Sie in einem Chat mit Sternchen fett machen. Hinter all dem steckt dieselbe Idee: Markdown. Markdown ist eine schlanke Auszeichnungssprache, mit der Sie Überschriften, Listen, Links und Tabellen festlegen, indem Sie reinem Text ein paar einfache Symbole hinzufügen. Die Datei bleibt in jedem Texteditor lesbar und lässt sich trotzdem jederzeit in eine saubere HTML-Seite, ein Word-Dokument oder eine PDF verwandeln. Dieser Artikel erklärt, wie Markdown entstanden ist, die grundlegende Syntax, die Unterschiede zwischen CommonMark und GitHub Flavored Markdown und worauf Sie beim Umwandeln von MD-Dateien achten sollten.

Was ist Markdown?

Markdown ist sowohl eine Sammlung von Schreibkonventionen als auch der gängige Name für Werkzeuge, die damit geschriebenen Text in HTML umwandeln. Dateien werden meist mit der Endung .md oder .markdown gespeichert. Laut seinem Erfinder John Gruber ist das oberste Gestaltungsziel die Lesbarkeit: Ein Markdown-Dokument soll sich so, wie es ist, als reiner Text veröffentlichen lassen, ohne nach Tags oder Formatierungsanweisungen auszusehen. Wo HTML <strong>wichtig</strong> braucht, schreibt Markdown **wichtig**, und selbst die Rohfassung liest sich natürlich.

Eine kurze Geschichte

John Gruber entwickelte Markdown 2004; Aaron Swartz wirkte als Gesprächspartner für seine Ideen mit. Die Syntax griff Konventionen aus Klartext-E-Mails auf (Sternchen für Hervorhebungen, Bindestriche für Listen) sowie frühere Auszeichnungssprachen wie setext und Textile. Version 1.0.1 von Markdown.pl, dem Perl-Skript, das Gruber auf seiner Website Daring Fireball veröffentlichte, ist auf den 17. Dezember 2004 datiert.

Grubers Beschreibung war allerdings eher eine Erklärung anhand von Beispielen als eine formale Spezifikation. In mehrdeutigen Fällen (verschachtelte Listen, eingerückte Codeblöcke, eingemischtes HTML) traf jede Implementierung eigene Entscheidungen, und derselbe Text führte in verschiedenen Werkzeugen zu unterschiedlicher Ausgabe. Darauf folgten zwei große Antworten:

• CommonMark (2014): eine von John MacFarlane geleitete Spezifikation, die Markdown eindeutig definiert und mit Hunderten Beispielen testbar macht. Die ersten Versionen erschienen im Herbst 2014; die aktuelle Version ist 0.31.2 vom 28. Januar 2024. Die Spezifikation wurde noch nicht zur Version 1.0 erklärt.
• GitHub Flavored Markdown (GFM, 2017): GitHubs formale Spezifikation auf Basis von CommonMark. Sie ergänzt Erweiterungen wie Tabellen, Aufgabenlisten, Durchstreichen, erweiterte Autolinks und aus Sicherheitsgründen das Filtern bestimmter roher HTML-Tags. Die zuletzt veröffentlichte Spezifikation ist 0.29-gfm vom 6. April 2019.

Auch in der Infrastruktur des Internets fand Markdown Anerkennung: RFC 7763 vom März 2016 registrierte den Medientyp (MIME-Typ) text/markdown mit einem optionalen Parameter variant, der angibt, welche Markdown-Variante der Autor gemeint hat.

Wichtige Markdown-Varianten

Neben CommonMark und GFM gibt es weitere verbreitete Varianten. RFC 7764, zusammen mit RFC 7763 veröffentlicht, registrierte mehrere davon und gab Hinweise zur Verwendung:

• Markdown Extra: eine frühe Erweiterung mit Fußnoten, Definitionslisten und Tabellen.
• MultiMarkdown: eine Variante für wissenschaftliches Schreiben mit Metadaten, Zitaten und Querverweisen.
• Pandoc Markdown: die Variante des Konverters Pandoc, mit vielen Erweiterungen zum Schreiben von Büchern und Fachartikeln.

Eine praktische Faustregel: Nutzt Ihr Dokument nur Überschriften, Listen, Links, Code und einfache Tabellen, sieht es fast überall gleich aus. Setzen Sie auf Fußnoten, Definitionslisten oder besondere Blocktypen, prüfen Sie, welche Variante die Zielumgebung unterstützt.

Grundlegende Syntax

Den Teil von Markdown, den Sie im Alltag brauchen, lernen Sie in wenigen Minuten:

# Überschrift erster Ebene
## Überschrift zweiter Ebene
Dieser Absatz enthält **fett**, *kursiv* und `Code`.
- Aufzählungsliste
- Zweiter Punkt
  - Eingerückter Unterpunkt
1. Nummerierte Liste
2. Zweiter Schritt
[Linktext](https://example.com)
![Bildbeschreibung](bild.png)
> Zitat
```
Mehrzeiliger Codeblock
```

Tabellen und Aufgabenlisten, die mit GFM hinzukamen, sehen so aus:

| Format | Endung |
|--------|--------|
| Markdown | .md |
| Reiner Text | .txt |
- [x] Entwurf schreiben
- [ ] Überarbeiten

Absätze werden durch Leerzeilen getrennt. Ein einfacher Zeilenumbruch gilt in den meisten Implementierungen als Teil desselben Absatzes; für einen erzwungenen Zeilenumbruch beenden Sie die Zeile mit zwei Leerzeichen. Sie können auch direkt HTML in Markdown schreiben. CommonMark erlaubt das, Umgebungen wie GFM sperren aber aus Sicherheitsgründen bestimmte Tags.

Wo wird Markdown eingesetzt?

• Softwareentwicklung: READMEs, Changelogs und Beitragsrichtlinien sowie Issues und Kommentare im Code-Review auf Plattformen wie GitHub und GitLab.
• Technische Dokumentation: statische Website-Generatoren, die Websites aus Markdown-Dateien bauen.
• Notizen: Viele Notiz-Apps speichern oder exportieren Notizen als Markdown.
• Chat- und Community-Plattformen: Plattformen wie Reddit und Discord nutzen Markdown-Varianten.
• Schreiben und Publizieren: HTML, PDF, DOCX und EPUB aus einer einzigen Markdown-Quelle mit Werkzeugen wie Pandoc erzeugen.
• KI-Werkzeuge: Chatbasierte KI-Assistenten formatieren ihre Antworten oft in Markdown.

Stärken und Schwächen

Welche Programme öffnen Markdown?

Weil Markdown reiner Text ist, öffnet es sich in jedem Texteditor, auch im Windows-Editor und in TextEdit. Für eine formatierte Vorschau können Sie die integrierte Markdown-Vorschau von Visual Studio Code oder spezielle Editoren wie Obsidian und Typora verwenden. GitHub und GitLab stellen .md-Dateien in Repositories automatisch formatiert dar. Word dagegen öffnet Markdown nicht als formatierten Text, die Datei muss also zuerst umgewandelt werden.

Typische Probleme und Lösungen

Eine Liste oder Überschrift wird nicht dargestellt

CommonMark verlangt nach dem Überschriftenzeichen ein Leerzeichen: ## Überschrift, nicht ##Überschrift. Eine Liste direkt nach einem Absatz braucht außerdem oft eine Leerzeile dazwischen, damit sie richtig erscheint.

Zeilen laufen ineinander

Ein einfacher Zeilenumbruch trennt keinen Absatz. Lassen Sie für einen neuen Absatz eine Leerzeile, oder beenden Sie die Zeile mit zwei Leerzeichen, um innerhalb eines Absatzes umzubrechen.

Eine Tabelle funktioniert auf einer Plattform, auf einer anderen nicht

Tabellen gehören weder zu Grubers ursprünglichem Markdown noch zum Kern von CommonMark; sie stammen aus Erweiterungen wie GFM. Prüfen Sie, welche Variante die Zielplattform unterstützt.

Ein Absatz, der mit einer Zahl beginnt, wird zur nummerierten Liste

Eine Zeile wie „2024. war ein ereignisreiches Jahr“ beginnt mit Ziffern und einem Punkt und kann deshalb als Liste gelesen werden. Maskieren Sie den Punkt mit einem Backslash (2024\.), um das zu verhindern.

Tipps zum Umwandeln von Markdown-Dateien

Bei unserem Konverter werden Markdown-Dateien auf unseren Server hochgeladen und innerhalb von 30 Minuten gelöscht. Zum Einlesen verwenden wir die Bibliothek Markdig mit CommonMark und Erweiterungen im GitHub-Stil (Tabellen, Aufgabenlisten, Fußnoten, Autolinks).

• Markdown in PDF und Markdown in Word behalten Überschriften, Listen, Codeblöcke, Zitate und Tabellen mit Rahmen. Kontrollkästchen aus Aufgabenlisten werden in die Zeichen ☑ und ☐ umgewandelt, damit sie in Word und PDF sichtbar bleiben. Text wird standardmäßig in einer 12-pt-Serifenschrift gesetzt, Codeblöcke in einer Festbreitenschrift.
• Markdown in HTML macht aus einer README eine eigenständige Webseite mit deklarierter Zeichenkodierung.
• In die andere Richtung erzeugen Word in Markdown, HTML in Markdown und PDF in Markdown GitHub-kompatibles Markdown: Überschriften, fetter und kursiver Text, Listen, Tabellen, Links, Codeblöcke und Zitate bleiben erhalten; Schriften, Farben und Seitenlayout entfallen. In Tabellen ohne Kopfzeile wird die erste Zeile zur Kopfzeile, weil GFM-Tabellen eine verlangen. Normale Absätze, die mit einer Zahl beginnen, etwa „1. Klausel“, werden maskiert, damit sie nicht versehentlich zu Listen werden. Die Datei wird als UTF-8 ohne BOM gespeichert.

Häufig gestellte Fragen

Wie öffne ich eine MD-Datei?

Jeder Texteditor öffnet sie. Formatiert sehen Sie sie in der Vorschau von Visual Studio Code oder in einem Markdown-Editor; wenn Sie sie in Word lesen möchten, wandeln Sie sie in DOCX um.

Was ist der Unterschied zwischen CommonMark und GitHub Flavored Markdown?

CommonMark legt die Kernsyntax von Markdown mit präzisen Regeln fest. GFM ist eine Obermenge, die CommonMark um Erweiterungen wie Tabellen, Aufgabenlisten, Durchstreichen und erweiterte Autolinks ergänzt.

Kann ich in Markdown Tabellen erstellen?

Ja, mit Erweiterungen wie GFM schreiben Sie einfache Tabellen mit senkrechten Strichen und Bindestrichen. Für komplexe Strukturen wie verbundene Zellen nutzen Sie eine HTML-Tabelle oder erstellen das Dokument in Word.

Was ist der Unterschied zwischen Markdown und HTML?

Markdown ist ein einfacheres Schreibformat, das für die Umwandlung in HTML gedacht ist. Es kann nicht alles ausdrücken, was HTML kann, ist in Rohform aber deutlich lesbarer. Bei Bedarf können Sie trotzdem HTML in Markdown schreiben.

Gibt es eine offizielle Norm für Markdown?

Grubers ursprüngliche Beschreibung ist keine formale Spezifikation. Die heute am breitesten akzeptierte präzise Definition ist CommonMark, und der Medientyp text/markdown wurde im März 2016 mit RFC 7763 registriert.

Quellen

• John Gruber, Daring Fireball: Markdown
• CommonMark Spec (Versionsgeschichte)
• GitHub Flavored Markdown Spec
• IETF RFC 7763: The text/markdown Media Type (März 2016)
• IETF RFC 7764: Guidance on Markdown
• Wikipedia: Markdown (Geschichte, Sekundärquelle)
• Markdig: ein CommonMark-konformer Markdown-Prozessor für .NET