Tabellen in Markdown: GFM-Syntax, Ausrichtung und Grenzen
GFM-Pfeiftabellen, Ausrichtung und Zellengrenzen.
Eine Markdown-Tabelle besteht aus einer Kopfzeile, einer Trennzeile mit Bindestrichen und den darunterliegenden Datenzeilen. Die Trennzeile ist es, die in GFM und in Hugo aus den Pipe-Symbolen eine Tabelle macht.
Dieser Leitfaden ist Teil von Dokumentationswerkzeuge 2026: Markdown, LaTeX, PDF & Druck-Workflows. Die anderen Blocktypen finden Sie im Markdown-Spickzettel.
Tabellen sind weder Teil der ursprünglichen Markdown-Syntax noch von CommonMark. Sie sind die Tabellen-Erweiterung in der GitHub Flavored Markdown-Spezifikation. Hugo 0.164 verwendet Goldmark mit dieser Erweiterung standardmäßig aktiviert (markup.goldmark.extensions.table). Die folgenden Beispiele sind eingefügt (fenced), damit die Pipe-Symbole wörtlich bleiben, was das Muster in Markdown-Codeblöcke ist.
Pipe-Tabellen-Syntax
Eine Tabelle besteht aus drei Teilen: einer Kopfzeile, einer Trennzeile und null oder mehreren Datenzeilen. Zellen werden durch | getrennt. Ein Pipe am Anfang und Ende einer Zeile ist optional. Leerzeichen neben einem Pipe werden entfernt.
| Kopf 1 | Kopf 2 |
| --- | --- |
| Zelle A1 | Zelle B1 |
| Zelle A2 | Zelle B2 |
Die Schreib-Dokumentationen von GitHub besagen, dass jede Trennzelle mindestens drei Bindestriche benötigt und dass eine Leerzeile vor der Tabelle erforderlich ist, damit GitHub sie rendert. Die GFM-Spezifikation beschreibt die Trennzelle als Bindestriche, mit optionalen Doppelpunkten auf einer oder beiden Seiten, und ihre Beispiele enthalten eine Zelle mit nur einem Bindestrich. Hugo 0.164 renderte dies als Tabelle:
| A | B |
| - | - |
| 1 | 2 |
Das gleiche Hugo-Rendering machte auch aus einer Tabelle ein <table>, wenn die vorherige Zeile ein Absatz war und keine Leerzeile existierte. Auf GitHub sollten Sie die Trennung mit drei Bindestrichen und die Leerzeile beibehalten. Auf dieser Website genügt ein Bindestrich und die Leerzeile ist nicht erforderlich.
|Zu|Eng| mit einer |---|---|-Trennung wurde ebenfalls gerendert. Leerzeichen neben den Pipes werden entfernt. Die Leerzeichen im ersten Beispiel sorgen dafür, dass eine Quellcode-Differenz lesbar bleibt.
Die Kopfzeile und die Trennzeile müssen die gleiche Anzahl an Zellen haben. Wenn sie sich unterscheiden, erkennt Hugo keine Tabelle. Dies bleibt gewöhnlicher Text, und die Bindestriche sind dann für den Hugo-Typographen geeignet:
| abc | def |
| --- |
| bar |
Eine Datenzeile kann kürzer oder länger als der Kopf sein. Eine kurze Zeile wird mit leeren Zellen aufgefüllt. Zellen über der Kopfzahl hinaus werden verworfen.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
Die erste dieser rendert eine leere dritte Zelle. Die zweite rendert nur 1 und 2.
Eine Zeile ohne Pipes ist immer noch innerhalb der Tabelle, bis eine Leerzeile erscheint. Hugo 0.164 setzte ein nachfolgendes bar in die Tabelle als eine Zeile mit einer leeren zweiten Zelle ein, im Einklang mit GFM-Beispiel 202. Der nächste Absatz beginnt nach der Leerzeile.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
Spaltenausrichtung
Die Ausrichtung erfolgt durch einen Doppelpunkt in der Trennzeile. --- ohne Doppelpunkt bedeutet linke Ausrichtung, ebenso wie :---.
| Links | Rechts | Mitte |
| :--- | ----: | :----: |
| text | 12.50 | ja |
| Links | Rechts | Mitte |
|---|---|---|
| text | 12.50 | ja |
Doppelpunkte in der Kopfzeile sind Zeichen in dieser Zelle. Sie setzen die Ausrichtung nicht. Die folgende Trennzeile ist es, die Hugo verwendete:
| :--- Links | Rechts ---: |
| :-------- | ---------- |
| Korrekt | Ausrichtung |
Zelleninhalt
Inlines funktionieren innerhalb einer Zelle: Hervorhebung, Code-Spanns und Links. Block-Strukturen funktionieren nicht. Die GFM-Spezifikation besagt, dass blockweise Elemente nicht in eine Tabelle eingefügt werden können, daher ist eine Liste oder ein eingefügter Block innerhalb einer Zelle keine Liste oder ein Zaun.
| Funktion | Status | Dokumentation |
| ---------- | ---------- | ------------- |
| **API v2** | *Veröffentlicht* | [Docs](/api) |
| `Auth` | Beta | Demnächst verfügbar |
Ein wörtliches Pipe ist \| oder |. Hugo 0.164 renderte beide als |.
| Ausdruck | Ergebnis |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
Ein Zeilenumbruch innerhalb einer Zelle ist ein HTML-<br>. Diese Website setzt markup.goldmark.renderer.unsafe auf true, daher bleibt dieses Tag erhalten. Eine Verarbeitung, die rohes HTML entfernt, verbindet die beiden Hälften.
Drei Bindestriche, die als Zelltext geschrieben werden, sind eine separate Falle in Hugo. Der Typograph schreibt --- in einer Zelle in einen Gedankenstrich um (—). Ein Code-Spann behält die Bindestriche bei. \--- wurde als -– gerendert.
| Als Text | Als Code |
| ------- | ------- |
| --- | `---` |
Verschmolzene Zellen
GFM hat kein rowspan oder colspan. Wenn eine Zelle zwei Zeilen abdecken muss, ist die Tabelle HTML. Der unsichere Renderer dieser Website lässt dieses HTML in der Seite:
<table>
<tr>
<td rowspan="2">Verschmolzen</td>
<td>Zelle 1</td>
</tr>
<tr>
<td>Zelle 2</td>
</tr>
</table>
Pands markdown+pipe_tables-Schreiber emittiert die Pipe-Syntax auf dieser Seite. Das ist der Schreiber, der verwendet wird, wenn man Word-Dokumente in Markdown konvertiert. Gittertabellen und andere nur-Pandoc-Layouts sind Dialekt-Features, die in GFM vs CommonMark vs Pandoc Markdown behandelt werden.
Eine breite Pipe-Tabelle scrollt oder läuft über. Die portablen Reduktionen sind ein transponiertes Layout, mehrere kleinere Tabellen oder eine HTML-Tabelle mit ihrem eigenen CSS. Die Pipe-Syntax hat keine Bildunterschrift. Der Inhaltsverzeichnis von Hugo wird aus Überschriften erstellt.
Prüfungen, wenn eine Tabelle als Text bleibt
Zählen Sie die Zellen in der Kopfzeile und der Trennzeile. Wenn sich diese beiden Zählungen unterscheiden, ist der Block ein Absatz. Eine kurze Datenzeile ist immer noch eine Tabelle, mit einer leeren Zelle am Ende. Die markdownlint-Regel MD056 verlangt, dass jede Zeile diese Anzahl entspricht, da eine kurze Zeile wie eine fehlende Zelle aussieht und eine zusätzliche Zelle verworfen wird.
Schauen Sie sich die Trennzeile auf die Doppelpunkte an. Ein Doppelpunkt in der Kopfzeile ist Text, und die Spalte bleibt bei der Ausrichtung der Trennzeile.
Wenn --- innerhalb einer Zelle auf dieser Website als einzelnes Bindestrich-Glyph erscheint, hat der Typograph es umgeschrieben. Setzen Sie die Bindestriche in einen Code-Spann.
Wenn GitHub die Pipes als Text anzeigt, fügen Sie die Leerzeile hinzu, die die GitHub-Dokumentationen erfordern, und verwenden Sie mindestens drei Bindestriche in jeder Trennzelle. Hugo 0.164 akzeptierte bereits die kürzere Form.
Eine fehlende Trennzeile ist die andere Art, wie ein Pipe-Block als Text bleibt. Hugo 0.164 ließ dies als Absatz:
| Kopf 1 | Kopf 2 |
| Zelle A | Zelle B |
Eine Parameter-Tabelle
Die gleiche Trennzeile trägt die Ausrichtung und lässt Raum für Inline-Code:
| Parameter | Typ | Standard | Erforderlich |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Ja |
| `timeout` | number | 30000 | Nein |
| `retries` | number | 3 | Nein |
