Markdown-Tabellen: Syntax und Praxis

Die grundlegende Syntax

Eine Markdown-Tabelle beginnt mit einer Kopfzeile, dann einer Trennzeile aus Bindestrichen, dann Datenzeilen. Spalten werden durch Pipes getrennt.

Die Trennzeile ist der Teil, der aus drei Zeilen eine Tabelle macht. Jede Spalte braucht dort mindestens einen Bindestrich und sonst nur optionale Doppelpunkte. Fehlt sie, rendern die Zeilen als normale Absätze – der häufigste Grund, warum eine Tabelle „nicht funktioniert“.

Tabellen sind eine GitHub-Flavored-Markdown-Erweiterung (GFM); der Renderer muss sie unterstützen, und die meisten modernen tun das. Auch müssen Sie die Pipes im Quelltext nicht ausrichten – Markdown ignoriert den Abstand, `|Tool|Typ|` und `| Tool | Typ |` rendern identisch.

| Tool | Typ |
| --- | --- |
| SHA-256 | Hashing |
| AES-GCM | Verschlüsselung |

Ausrichtung steuern

Doppelpunkte in der Trennzeile steuern die Ausrichtung: :--- links, :---: mittig, ---: rechts.

Der Doppelpunkt ist das Entscheidende; die Bindestriche sind Füllmaterial. Linksbündig ist der Standard, daher sehen `---` und `:---` bei den meisten Renderern gleich aus.

Ausrichtung ist ein Darstellungshinweis, keine Dateneigenschaft. Rechtsbündige Zahlen stehen an der Dezimalstelle übereinander und lassen sich so besser vergleichen. Nicht jeder Renderer beachtet das allerdings – manche ignorieren die Doppelpunkte; prüfen Sie das Zielsystem.

| Links | Mitte | Rechts |
| :--- | :---: | ---: |
| 1 | 2 | 3 |
| 10 | 20 | 30 |

Pipes und Sonderzeichen escapen

Um eine echte Pipe innerhalb einer Zelle darzustellen, escapen Sie sie mit einem Backslash: \|. Code-Spans und Links funktionieren normal in Zellen.

Das Backslash-Escaping wird verarbeitet, bevor die Zelle aufgeteilt wird; deshalb funktioniert \| auch in Inline-Code und fettem Text. Eine Shell-Pipeline wie `ps \| grep node` bleibt in einer Zelle.

Links, Betonung und Inline-Code werden in Zellen normal geparst. Nicht möglich ist verschachtelter Blockinhalt – keine Listen, Überschriften oder Codeblöcke in einer Zelle; das gehört außerhalb der Tabelle.

• Pipes escapen: \| innerhalb einer Zelle
• Inline-Code mit Backticks: `npx tsx`
• Links funktionieren in Zellen: Dokumentation
• Zellen kurz halten; langer Text gehört in Listen oder Abschnitte
• Ein mit Backslash gescapeter Pipe funktioniert auch in Backticks und fettem Text

Tabellen vs. Listen

Eine Tabelle lohnt sich, wenn jede Zeile dieselbe Frage mit einem anderen Wert beantwortet: Parameterlisten, Algorithmenvergleiche, Änderungsprotokolle mit festen Spalten. Lesen sich die Zeilen wie Sätze, ist eine Liste meist die bessere Form.

Denken Sie an Leser auf dem Smartphone. Eine Tabelle mit vier Spalten und langer URL-Spalte wird zum horizontalen Scrollen – und viele scrollen nicht. Teilen Sie die Tabelle auf oder kürzen Sie breite Inhalte auf Linktext.

Meine Faustregel: Wenn ich ein CLI-Tool dokumentiere, halte ich Tabellen auf drei Spalten und lege lange Beispiele in einen eigenen Codeblock darunter.

• Tabellen für Vergleiche, Parameter und strukturierte Daten
• Listen für Abläufe, Optionen und textlastige Inhalte
• Auf Mobilgeräten 3-5 Spalten nicht überschreiten, um horizontales Scrollen zu vermeiden
• Braucht eine Tabelle verschachtelte Inhalte, teilen Sie sie in kleinere Tabellen oder Prosa
• Listen verwenden, wenn die Reihenfolge wichtig ist und jeder Punkt für sich steht
• Kopfzeilen kurz halten, damit Screenreader sie sauber ansagen

Lokal prüfen und verfeinern

Die Markdown-Vorschau rendert lokal in Ihrem Browser – ein guter Ort, um mit Doppelpunkten und Escaping zu experimentieren. Halten Sie Quelltext und Vorschau nebeneinander.

1. Schreiben Sie Ihre Tabelle in Markdown.
2. Öffnen Sie die Markdown-Vorschau in Ihrem Browser.
3. Fügen Sie den Quelltext ein und prüfen Sie die gerenderte Ausrichtung.
4. Passen Sie Doppelpunkte und Escaping an, bis die Tabelle sauber liest, dann exportieren oder kopieren.
5. Prüfen Sie den Rohquelltext noch einmal: Eine ungescapete Pipe oder eine fehlende Trennzeile ist der häufigste Grund.
6. Testen Sie denselben Quelltext dort, wo die Dokumentation später lebt – GitHub, GitLab oder Ihr CMS –, denn Renderer unterscheiden sich.

FAQ

Referenzen

• GitHub Flavored Markdown Spec – Tables: https://github.github.com/gfm/#tables-extension-
• CommonMark Specification: https://spec.commonmark.org/
• RFC 7763 – The text/markdown Media Type: https://www.rfc-editor.org/info/rfc7763/
• RFC 7764 – Guidance on Markdown: https://www.rfc-editor.org/info/rfc7764/
• Originale Markdown-Syntax (John Gruber): https://daringfireball.net/projects/markdown/syntax
• MDN – How to write in Markdown: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN