Markdown

Was ist Markdown?

Markdown ist eine leichtgewichtige Auszeichnungssprache: Sie schreiben Klartext mit wenigen Satzzeichen, etwa # für eine Überschrift oder * für Betonung, und ein Konverter macht daraus HTML. John Gruber veröffentlichte es 2004 mit Hilfe von Aaron Swartz mit dem Ziel, schon vor der Umwandlung möglichst gut lesbar zu sein. Dateien enden meist auf .md.

So funktioniert Markdown

Ein Parser liest den Text und erzeugt HTML. Dieselbe Quelle kann eine Webseite, eine README oder eine Dokumentationsseite speisen.

• # Titel wird zur Überschrift, mehr # ergeben tiefere Ebenen.
• **fett** und *kursiv* kennzeichnen Hervorhebungen.
• - Punkt beginnt eine Aufzählung, 1. Punkt eine nummerierte Liste.
• [Text](https://example.com) erzeugt einen Link, ![Alt](bild.png) ein Bild.
• Backticks umschließen Inline-Code, drei Backticks einen Codeblock.

Varianten und Spezifikation

Grubers ursprüngliche Beschreibung ließ viele Fälle offen, etwa wie weit eine Unterliste eingerückt sein muss, daher stellten Implementierungen dieselbe Datei unterschiedlich dar. Die CommonMark-Spezifikation (Version 0.31.2, Januar 2024) legt die Syntax eindeutig fest und enthält Beispiele, die zugleich als Tests dienen. GitHub Flavored Markdown ist eine strikte Obermenge von CommonMark und ergänzt Tabellen, Aufgabenlisten, Durchstreichungen und erweiterte Autolinks. Prüfen Sie daher, welche Variante Ihr Tool nutzt.

Beispiel

Eine Projekt-README beginnt etwa mit # Payments API, einer Kurzbeschreibung, einer Liste der Endpunkte und einem Codeblock mit einer Beispielanfrage. Im Repository wird sie als formatierte Seite angezeigt. In einem Static-Site-Generator (siehe statische Seitengenerierung) wird dieselbe Datei beim Build zur Webseite.

Häufige Fehler

• Die Leerzeile vor Liste oder Überschrift vergessen, die viele Parser brauchen.
• Tabellen oder Aufgabenlisten nutzen und annehmen, jeder Renderer unterstütze sie.
• Überschriftenebenen überspringen, was Gliederung und Barrierefreiheit schadet.
• Nicht vertrauenswürdiges Markdown ohne Bereinigung des erzeugten HTML einbinden.
• Markdown für Layout nutzen, das es nicht ausdrücken kann, wo Rich Text oder HTML besser passt.

Markdown in Dokumentation und Tests

Teams halten Doku, Changelogs und Testpläne in Markdown neben dem Code, sodass sie durch dasselbe Review und dieselbe CI laufen. Wiederverwendbare Teile passen gut zu einem Content-Block. LoadFocus veröffentlicht seine Produktanleitungen in der Dokumentation. Für Pipelines, die bei jedem Commit prüfen, siehe den Leitfaden zu GitHub Actions (englisch).

Häufige Fragen zu Markdown

Wofür wird Markdown verwendet?

Für READMEs, Dokumentation, Blogbeiträge, Notizen und Chatnachrichten in Klartext, der sich in HTML umwandeln lässt. Beliebt ist es, weil die Quelle lesbar bleibt und gut zur Versionsverwaltung passt.

Was ist der Unterschied zwischen Markdown und HTML?

HTML beschreibt eine Seite mit Tags und deckt alles im Web ab. Markdown ist eine kürzere Syntax für übliche Strukturen wie Überschriften, Listen und Links und wird in HTML umgewandelt. Rohes HTML lässt sich oft einmischen.

Was ist CommonMark?

CommonMark ist eine Spezifikation, die die Markdown-Syntax eindeutig definiert, mit Beispielen als Konformitätstests. Sie entstand, weil die ursprüngliche Beschreibung viele Fälle offenließ.

Was ist GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) ist eine strikte Obermenge von CommonMark. Es ergänzt Tabellen, Aufgabenlisten, Durchstreichungen und erweiterte Autolinks.

Wie wandle ich Markdown in HTML um?

Mit einem Markdown-Parser oder einem Tool, das einen enthält, etwa einem Static-Site-Generator, einer Editor-Vorschau oder einem Kommandozeilen-Konverter. Bereinigen Sie die Ausgabe, wenn das Markdown von Nutzern stammt.