GitHub Flavored Markdown (GFM): Was es kann und wie du es nutzt

Wer schon einmal eine README auf GitHub gesehen hat, mit einer sauberen Tabelle, abhakbaren To-do-Punkten und farbig hervorgehobenem Code, hat GitHub Flavored Markdown in Aktion erlebt. Diese Elemente sind im ursprünglichen Markdown gar nicht vorgesehen. Sie kamen erst mit GFM dazu und haben sich so weit verbreitet, dass viele sie für selbstverständlichen Markdown-Standard halten. In diesem Ratgeber klären wir, was genau zu GFM gehört, wie Sie die einzelnen Funktionen schreiben und wo ihre Grenzen liegen.

GFM und CommonMark: der Unterschied

Um GFM zu verstehen, muss man zwei Begriffe auseinanderhalten. CommonMark ist die streng definierte Spezifikation des Markdown-Kerns. Sie legt genau fest, wie Überschriften, Absätze, Listen, Hervorhebungen, Links, Bilder und Code zu verstehen sind. CommonMark entstand, weil das ursprüngliche Markdown nicht eindeutig genug definiert war und verschiedene Programme es leicht unterschiedlich auslegten. Heute ist CommonMark die verlässliche Grundlage fast aller Werkzeuge.

GitHub Flavored Markdown baut auf CommonMark auf und erweitert es um vier zusätzliche Funktionen. GitHub hat diese Erweiterungen eingeführt, weil sie im Alltag von Software-Projekten ständig gebraucht werden. Die folgende Tabelle, selbst in GFM geschrieben, zeigt den Unterschied:

| Funktion       | CommonMark | GFM |
| -------------- | ---------- | --- |
| Überschriften  | Ja         | Ja  |
| Tabellen       | Nein       | Ja  |
| Task-Listen    | Nein       | Ja  |
| Durchgestrichen| Nein       | Ja  |

Wichtig: GFM ersetzt CommonMark nicht, sondern legt sich darüber. Alles, was Sie aus dem Markdown-Kern kennen, funktioniert in GFM genauso. Eine kompakte Übersicht aller Grundelemente bietet der Markdown-Spickzettel sowie die Markdown-Syntax-Übersicht.

Tabellen in GFM

Tabellen sind wohl die meistgenutzte GFM-Erweiterung. Sie entstehen durch senkrechte Striche, die Pipe-Zeichen, die die Spalten trennen, und eine Trennzeile aus Bindestrichen unter der Kopfzeile. Das Beispiel oben zeigt genau diese Struktur: Die erste Zeile ist die Kopfzeile, die zweite mit den Bindestrichen ist Pflicht, und alle weiteren Zeilen sind Datenzeilen. Über Doppelpunkte in der Trennzeile lässt sich sogar die Ausrichtung steuern. Wie das im Detail funktioniert, erklärt der Ratgeber Markdown-Tabelle erstellen. Wer eine bestehende HTML-Tabelle übernehmen möchte, findet im Ratgeber HTML-Tabelle in Markdown umwandeln den passenden Weg.

Task-Listen mit abhakbaren Kästchen

Task-Listen verwandeln eine normale Aufzählung in eine Checkliste. Hinter dem Listenzeichen steht ein Kästchen in eckigen Klammern: ein Leerzeichen für eine offene Aufgabe, ein x für eine erledigte. Auf GitHub und ähnlichen Plattformen werden diese Kästchen sogar interaktiv und lassen sich per Mausklick abhaken.

## Aufgaben

- [x] Konzept geschrieben
- [x] Entwurf abgestimmt
- [ ] Korrektur eingearbeitet
- [ ] Veröffentlicht

Task-Listen eignen sich hervorragend für Projektpläne, Pull-Request-Beschreibungen oder einfache To-do-Listen in der Dokumentation. Sie geben auf einen Blick den Fortschritt wieder, ohne dass man dafür ein eigenes Werkzeug braucht.

Durchgestrichener Text und Autolinks

Durchgestrichener Text entsteht durch zwei Tilden vor und hinter dem Wort. Das eignet sich, um Überholtes sichtbar zu lassen, statt es zu löschen, etwa bei einer Terminänderung:

Der Termin am ~~Montag~~ Mittwoch bleibt bestehen.

Autolinks sind die wohl unauffälligste, aber bequemste Erweiterung. In reinem CommonMark müssen Sie eine Webadresse in eckige und runde Klammern setzen, damit sie zum Link wird. GFM erkennt eine vollständige URL im Fließtext automatisch und macht sie klickbar, ganz ohne zusätzliche Zeichen:

Mehr Infos unter https://html-md.de finden Sie sofort.

Fenced Code mit Syntax-Highlighting

Fenced Code-Blöcke werden mit drei Backticks eingeleitet und beendet. Der Clou bei GFM: Direkt hinter die einleitenden Backticks schreiben Sie den Namen der Programmiersprache. Plattformen wie GitHub färben den Code daraufhin passend ein, was ihn deutlich lesbarer macht.

```js
function begruessung(name) {
  return `Hallo, ${name}!`;
}
```

Die Sprachangabe steuert allein die farbliche Hervorhebung, sie ändert den Code nicht. Lassen Sie sie weg, bleibt der Block trotzdem als Code formatiert, nur eben ohne Einfärbung. Für längere Codebeispiele in einer README sind fenced Blöcke mit Sprachangabe der Standard.

GFM im Tool aktivieren

Auf html-md.de ist GFM fest eingeplant. Für die Richtung von Markdown nach HTML ist es standardmäßig aktiv, sodass Tabellen, Task-Listen und Code-Blöcke direkt korrekt in HTML übersetzt werden. Für die Gegenrichtung, also von HTML nach Markdown, finden Sie in den Optionen einen GFM-Schalter. Ist er eingeschaltet, werden HTML-Tabellen in GFM-Tabellen, durchgestrichener Text und ähnliche Konstrukte sauber übernommen. Ist er aus, beschränkt sich die Ausgabe auf den CommonMark-Kern.

Wann sollten Sie den Schalter aktivieren? Immer dann, wenn das Ziel eine Plattform ist, die GFM versteht, also etwa GitHub, GitLab oder ein modernes Wiki. Die genauen Schritte für die Umwandlung beschreiben die Ratgeber HTML in Markdown umwandeln und Markdown in HTML umwandeln.

Wo GFM funktioniert und wo nicht

GFM hat sich weit verbreitet, ist aber kein allgemeingültiger Standard. Auf GitHub, GitLab und vielen modernen Editoren und Wikis können Sie sich darauf verlassen, dass Tabellen, Task-Listen und durchgestrichener Text korrekt dargestellt werden. Auch der Konverter auf html-md.de unterstützt diese Elemente.

Es gibt jedoch Systeme, die nur den CommonMark-Kern oder einen anderen Dialekt verstehen. Dort kann es passieren, dass eine GFM-Tabelle als roher Text mit Pipe-Zeichen erscheint oder ein Kästchen einer Task-Liste schlicht als Klammern stehen bleibt. Ältere Foren, manche E-Mail-Programme oder strikt an CommonMark gehaltene Generatoren gehören dazu. Faustregel: Prüfen Sie im Zweifel, welchen Dialekt das Zielsystem erwartet, und sehen Sie sich das Ergebnis kurz an. Erscheint eine Erweiterung nicht wie gewünscht, kennt das System sie vermutlich nicht.

Auch innerhalb von GFM gibt es Grenzen. Sehr komplexe Tabellen mit verbundenen Zellen lassen sich nicht abbilden, dafür braucht es echtes HTML. Und Erweiterungen anderer Dialekte wie Fußnoten, mathematische Formeln oder Diagramme gehören nicht zum GFM-Standard und werden je nach Plattform unterschiedlich oder gar nicht unterstützt. Wer diese Feinheiten kennt, vermeidet Überraschungen und nutzt GFM dort, wo es wirklich glänzt: in der täglichen Arbeit mit Code, Dokumentation und Projektplanung. Am schnellsten sehen Sie das Ergebnis, wenn Sie ein Beispiel direkt im Konverter ausprobieren.

Häufige Fragen