Vor Kurzem kam aus unserer Community die Frage, wie sich einzelne Tabellenzeilen in AsciiDoc farbig hervorheben lassen und wie Listen in Tabellenzellen funktionieren. Beides wirkt zunächst unmöglich, ist es aber nicht. Hier sind drei CSS-Muster für die Zeilenhervorhebung und der AsciiDoc-Modifikator, der Block-Inhalte in Zellen freischaltet. Inklusive klarer Empfehlung am Ende.
Warum sich Zeilen in AsciiDoc nicht out of the box einfärben lassen
AsciiDoc-Tabellen sind auf der Eingabeseite stark. Ein paar Pipes, eine Header-Zeile, fertig. Auf der Ausgabeseite wird es heikel. asciidoctor rendert Ihren |===-Block zu schlichtem <table><tr><td>-HTML. Eine eingebaute Syntax für Zeilenfarben gibt es nicht, und eine Standardzelle akzeptiert nur Inline-Inhalt. Listen oder Admonitions erscheinen daher schlicht als Text.
Die Lösung liegt auf zwei Ebenen. AsciiDoc-Rollen wie [.highlight] werden im gerenderten HTML zu CSS-Klassen. Das ist der Hook. Die eigentliche Gestaltung übernimmt CSS. Für Block-Inhalte in Zellen schaltet der a|-Modifikator einzelne Zellen oder ganze Spalten in den vollen AsciiDoc-Modus.
Drei Bausteine, also Rollen, CSS und a|, decken beide Probleme zuverlässig ab. Das gleiche Muster funktioniert sowohl bei HTML-Export mit asciidoctor als auch beim PDF-Export via asciidoctor-pdf. Die Tabellen-Syntax selbst ist im Tabellen-Abschnitt unseres Handbuchs verbindlich dokumentiert.
Listen in AsciiDoc-Tabellenzellen einfügen
Das ist die einfachere der beiden Fragen. AsciiDoc kennt einen eigenen Zellmodus für Block-Inhalte. Sie aktivieren ihn entweder pro Zelle mit a| oder pro Spalte mit cols="...a...". Eine Auffrischung der Grundsyntax bieten unsere Lernpfad-Module zu Listen und Hinweisen.
Einzelne Zelle mit a|
Das a| ersetzt das normale | für genau eine Zelle. Der Rest der Tabelle bleibt im Standardmodus. Das ist wichtig, denn so werden Inline-Sternchen oder Pluszeichen nicht versehentlich als Block-Syntax interpretiert.
[cols="1,2"]
|===
| Normale Zelle | Standardtext ohne Block-Features
| Zelle mit Liste
a|
* Funktioniert
* Auch ohne `cols="1a"`
** Untergeordnet
| Wieder normal | Einfacher Text
|===Nutzen Sie diese Variante, wenn Block-Inhalte nur vereinzelt auftauchen und der Rest der Tabelle schlichter Text bleibt.
Ganze Spalte mit cols="...a..."
Kommen in einer Spalte regelmäßig Block-Inhalte vor, lohnt sich der a-Modifier direkt in der cols-Spezifikation. Jede Zelle dieser Spalte ist dann automatisch im AsciiDoc-Modus, ohne dass a| pro Zeile wiederholt werden muss.
[cols="1a,2a", options="header"]
|===
| Feature | Beschreibung
| Geschachtelte Liste
|
* Hauptpunkt A
** Unterpunkt A.1
** Unterpunkt A.2
* Hauptpunkt B
| Admonition
|
NOTE: Auch Admonitions funktionieren in nested Tables.
|===Ein Nebeneffekt sollte Ihnen bewusst sein: Im spaltenweiten AsciiDoc-Modus wird ein führendes Sternchen in Klartext zum Bullet. Wenn ein literales * literal bleiben soll, bevorzugen Sie die zellenspezifische Variante mit a|.
Drei Ansätze zum Einfärben von Zeilen und Zellen in AsciiDoc-Tabellen
Es gibt kein Attribut [row-color=yellow] in AsciiDoc. Stattdessen gibt es drei Muster, die zu vergleichbaren Ergebnissen führen, aber sehr unterschiedliche Konsequenzen haben. Variante A ist in fast allen Fällen unsere Empfehlung.
Variante A: Utility-Klasse pro Zelle (Empfehlung)
Die Idee ist einfach. Sie markieren Zellen mit einer Inline-Rolle wie [.highlight]#Text#. AsciiDoc rendert das als <span class="highlight"> innerhalb der <td>. Eine einzige CSS-Regel mit :has() färbt anschließend die umschließende Zelle.
[cols="1,2,1", options="header"]
|===
| Feature | Beschreibung | Status
| Login | Standard-Implementierung | OK
| [.highlight]#2FA# | [.highlight]#Komplette Zeile gelb# | [.highlight]#Review#
| Logout | Funktioniert | OK
| Passwort-Reset | [.highlight]#Nur diese eine Zelle# | OK
|===Für eine einzelne Zelle markieren Sie nur diese eine. Für eine komplette Zeile setzen Sie die Rolle in jeder Zelle der Zeile. Verschiedene Farben innerhalb einer Zeile funktionieren genauso: andere Klasse pro Zelle.
Das passende CSS nutzt :has(), um die <td> einzufärben, sobald sie ein Markierungs-Span enthält. Weitere Farben sind je eine zusätzliche Regel:
table.tableblock td:has(.highlight) { background-color: #FFF59D; }
table.tableblock td:has(.highlight-red) { background-color: #FFCDD2; }
table.tableblock td:has(.highlight-green) { background-color: #C8E6C9; }
table.tableblock td:has(.highlight-blue) { background-color: #BBDEFB; }
.highlight,
.highlight-red,
.highlight-green,
.highlight-blue { background: transparent; }Die Markierungs-Spans selbst sind transparent gesetzt. Nur die umliegende Zelle bekommt also Farbe. Verschieben Sie Zeilen nach Belieben: Die Hervorhebung folgt dem Inhalt, nicht der Position.
Eine Einschränkung: :has() braucht eine moderne Rendering-Engine. Alle aktuellen Browser unterstützen es. Bei asciidoctor-pdf prüfen Sie vor dem Festlegen kurz, ob Ihre Stylesheet-Pipeline :has() versteht. Dieselbe Brücke von Rolle zu CSS-Klasse trägt übrigens auch ganze Site-Templates und Navigationen, wie unser Beitrag zu Website-Elementen in AsciiDoc-Exporten via Docinfo zeigt und wie es das Kapitel Gestaltung mit CSS unseres Handbuchs durchgängig beschreibt.
Variante B: Tabellen-Rolle plus nth-child
Wenn die Tabelle tatsächlich eine Status-Legende mit fester Zeilenreihenfolge ist, können Sie das gesamte Wissen ins CSS verlagern. Sie geben der Tabelle eine Rolle und färben Zeilen über ihren Index.
[.status-table]
[cols="1,2,1", options="header"]
|===
| Status | Beschreibung | Priorität
| Normal | Standard-Zeile | Niedrig
| Warnung | Zeile 2 -> gelb laut Theme | Mittel
| Fehler | Zeile 3 -> rot laut Theme | Hoch
| OK | Zeile 4 -> grün laut Theme | Niedrig
|===table.status-table tbody tr:nth-child(1) { background-color: transparent; }
table.status-table tbody tr:nth-child(2) { background-color: #FFF59D; }
table.status-table tbody tr:nth-child(3) { background-color: #FFCDD2; }
table.status-table tbody tr:nth-child(4) { background-color: #C8E6C9; }Im AsciiDoc kompakt, aber positional. Verschiebt sich eine Zeile nach oben, bleiben die Farben am alten Index. Setzen Sie diese Variante nur ein, wenn die Reihenfolge Teil der Bedeutung ist.
Variante C: Rein positional
Auf der AsciiDoc-Seite steht nichts außer einer Hook-Rolle, die das CSS gezielt auf diese eine Tabelle eingrenzt. Sinnvoll bei Legacy-Inhalten, die Sie nicht anfassen können, oder bei wiederkehrenden Schablonen mit immer gleichem Aufbau.
[.positional-demo]
[cols="1,2,1", options="header"]
|===
| Status | Beschreibung | Priorität
| Normal | Standard-Zeile | Niedrig
| Warnung | Diese Zeile ist gelb | Mittel
| Normal | Normale Zeile dazwischen | Niedrig
| Fehler | Diese Zeile ist rot | Hoch
| OK | Normale Zeile | Niedrig
|===table.positional-demo tbody tr:nth-child(2) {
background-color: #FFF59D;
}
table.positional-demo tbody tr:nth-child(4) {
background-color: #FFCDD2;
}Die Hook-Rolle verhindert, dass der Selektor in andere Tabellen auf der Seite hineinblutet. Davon abgesehen gilt derselbe Trade-off wie bei Variante B, nur mit noch weniger Kontext im AsciiDoc.
Variante A mit Liste in einer Zelle kombinieren
Spannend wird es, wenn eine hervorgehobene Zelle zusätzlich eine Liste enthalten soll. Für Block-Inhalte funktioniert die Inline-Rolle [.highlight]#...# nicht, weil sie nicht den ganzen Block umschließt. Stattdessen nutzen Sie [.highlight] als Block-Rolle auf einem Open Block. Innerhalb einer a|-Zelle entsteht so das Markierungs-<div>, das die td:has(.highlight)-Regel braucht.
[cols="1,3a", options="header"]
|===
| Feature | Details
| [.highlight]#2FA#
|
[.highlight]
--
Diese Zelle ist markiert und enthält trotzdem eine Liste:
* TOTP via Authenticator
* SMS-Fallback
* Recovery Codes
--
| Logout
| Standard ohne Markierung.
|===Die ---Zeilen definieren den Open Block. Block-Rolle oben drauf, dazwischen freier AsciiDoc-Inhalt. Die :has()-Regel aus Variante A findet das .highlight-div und färbt die gesamte <td>.
Welcher Ansatz passt
Für nahezu jedes Team, das echte Inhalte aus Confluence, Word oder anderen Legacy-Quellen migriert, ist Variante A der richtige Startpunkt. Sie skaliert auf einzelne Zellen, ganze Zeilen, gemischte Farben pro Zeile und beliebige Muster. Neue Farben sind eine zusätzliche CSS-Regel. Zeilen lassen sich verschieben, ohne die visuelle Logik zu zerstören. Und sie kombiniert sich sauber mit a| für Zellen, die Listen, Code oder Admonitions enthalten.
- Variante A: der Standard. Das Markup trägt die Semantik, CSS übernimmt das Styling. Übersteht Zeilenumsortierung.
- Variante B: nur, wenn die Tabelle eine Status-Legende mit fester Reihenfolge ist und der Zeilenindex Bedeutung trägt.
- Variante C: nur, wenn Sie den AsciiDoc-Quelltext nicht ändern können und das Schema stabil bleibt.
Aus dem Docs-as-Code Café
Diese Frage kam aus unserem Docs-as-Code Café, einer deutschsprachigen Discord-Community für technische Redakteurinnen und Redakteure. Wir treffen uns dort zu AsciiDoc, Markdown, Toolchains und allem rund um Docs-as-Code.
Lust auf fachlichen Austausch und gemeinsames Knobeln an genau solchen Fragen? Kommen Sie dazu.
Fazit
Rollen, CSS und a| sind das komplette Werkzeug, um AsciiDoc-Tabellen zu gestalten. Sobald diese drei Bausteine sitzen, ist die Wahl zwischen Zeilenhervorhebung und reichhaltigem Zellinhalt keine Frage der AsciiDoc-Syntax mehr. Es wird zur Frage, wie viel Information Sie im Markup tragen wollen und wie viel im Stylesheet.
Für weitere Gestaltungsthemen rund um AsciiDoc-Ausgabe lesen Sie unseren Beitrag zum Tufte-Stil in adoc Studio und unsere Muster zur Modularisierung von AsciiDoc-Dokumenten. Für den tieferen Einstieg in die AsciiDoc-Tabellensyntax arbeiten Sie das Tabellen-Modul unseres Lernpfads durch und schlagen ergänzend in der AsciiDoc-Referenz des Handbuchs nach. Den größeren Zusammenhang zur Trennung von Inhalt und Darstellung lesen Sie in unserem Docs-as-Code-Leitfaden. Wenn Sie noch mitten in der Umstellung aus Confluence, Word oder DITA stecken, sammelt unser pragmatisches Migrations-Playbook die praktischen Schritte.
FAQ: Häufige Fragen zum Styling von AsciiDoc-Tabellen
Kann ich in AsciiDoc einzelne Tabellenzeilen einfärben?
Nicht mit eingebauter Syntax. AsciiDoc kennt kein Attribut wie row-color. Sie nutzen CSS, das Sie über Rollen ansteuern. Das flexibelste Muster: [.highlight]#Text# in jeder Zelle der Zeile, kombiniert mit td:has(.highlight) im CSS.
Wie bekomme ich eine Liste in eine AsciiDoc-Tabellenzelle?
Setzen Sie a| vor die Zelle, um sie in den AsciiDoc-Modus zu schalten. Für eine komplette Spalte verwenden Sie cols="...a...". Innerhalb einer Zelle im AsciiDoc-Modus funktionieren Listen, Codeblöcke und Admonitions wie gewohnt.
Funktioniert das mit asciidoctor-pdf?
Variante A setzt auf den CSS-Selektor :has(). Aktuelle Browser unterstützen ihn, ebenso die neueren asciidoctor-pdf-Versionen. Prüfen Sie Ihre Stylesheet-Pipeline einmal kurz, bevor Sie sich darauf festlegen. Varianten B und C nutzen nur nth-child, das universell unterstützt wird.
Warum funktioniert `[.highlight]#…#` nicht in einer Zelle mit Liste?
Die Inline-Form umschließt nur Inline-Inhalt. Für Block-Inhalte wie Listen nutzen Sie [.highlight] als Block-Rolle auf einem Open Block (-- … --). So entsteht ein <div class="highlight">, das die :has()-Regel finden kann.
Was ist der Unterschied zwischen `a|` und `cols=”…a…”`?
a| schaltet genau eine Zelle in den AsciiDoc-Modus. cols="...a..." schaltet jede Zelle einer Spalte. Nutzen Sie die Spalten-Variante, wenn Block-Inhalt die Regel ist, und die Zell-Variante, wenn er die Ausnahme bleibt. Im Spalten-Modus werden führende Sternchen im Klartext sonst zu Bullet-Punkten.
Sind AsciiDoc-Rollen dasselbe wie CSS-Klassen?
Praktisch ja. Eine Rolle wie [.highlight] auf Inline-Inhalt wird zu <span class="highlight">. Auf einem Block wird sie zur CSS-Klasse auf dem Block-Element. Von dort übernimmt CSS. Das ist genau die Brücke, mit der wir auch komplette Website-Templates an AsciiDoc-Exporte anbinden.
Download