AsciiDoc tables

Components•6 min read|
|

Use wc-asciidoc-table when you want readable, hand-authored tables with features Markdown tables do not cover — multi-line cells, column widths, spans, alignment, and CSV/DSV data.

DocsLit parses a focused subset of AsciiDoc table syntax at build time and emits a real HTML <table> (good for SEO and static hosting).

Basic table

Wrap an AsciiDoc table block in wc-asciidoc-table:

<wc-asciidoc-table> [cols="1,2,3",options="header"] |=== |Method |Path |Description |GET |/users |List users |POST |/users |Create a user |=== </wc-asciidoc-table>
MethodPathDescription
GET/usersList users
POST/usersCreate a user
  • Markdown (GFM) — small, simple tables
  • wc-table — JSON-driven data with sticky headers
  • wc-asciidoc-table — hand-authored tables with spans, column specs, multi-line cells, or CSV/DSV

Implicit header row

If every cell of the first row is on the line right after |===, and the next line is blank, that row becomes the header automatically:

<wc-asciidoc-table> |=== |Name |Role |Team |Ada |Engineer |Platform |Grace |Admiral |Navy |=== </wc-asciidoc-table>
NameRoleTeam
AdaEngineerPlatform
GraceAdmiralNavy

You can also set the header explicitly with options="header" or %header in the attribute list.

Column specs

Use cols to set column count, relative widths, default alignment, and default cell style:

<wc-asciidoc-table> [cols="2,1,3",options="header"] |=== |Wide |Narrow |Widest |Left content |Mid |More detail on the right |=== </wc-asciidoc-table>
WideNarrowWidest
Left contentMidMore detail on the right

Multipliers and alignment

SpecMeaning
3*Three equal columns
2,3*One column width 2, then three equal columns
> / < / ^Right / left / center horizontal align
.> / .< / .^Bottom / top / middle vertical align
s e m h l aStrong, emphasis, mono, header, literal, AsciiDoc cell
~Autowidth column
<wc-asciidoc-table> [cols=">s,3*^"] |=== |Right + strong |Center |Center |Center |Emphasis |a |b |c |=== </wc-asciidoc-table>
Right + strongCenterCenterCenter
Emphasisabc

Cell spans, styles, and alignment

Put operators immediately before the cell separator (|):

<wc-asciidoc-table> |=== |Feature |Notes 2+|Spans both columns |Right aligned >|Aligned to the right |Strong s|Bold cell text |Monospace m|GET /v1/items |Emphasis e|Italic cell text |=== </wc-asciidoc-table>
FeatureNotes
Spans both columns
Right alignedAligned to the right
StrongBold cell text
MonospaceGET /v1/items
EmphasisItalic cell text

Span operators

OperatorEffect
2+|Span 2 columns
.2+|Span 2 rows
2.2+|Span 2 columns and 2 rows
3*|Repeat the cell across 3 columns
<wc-asciidoc-table> [cols="3*"] |=== |A |B |C 2.2+|Block span |Row 1 Col 3 |Row 2 Col 3 |D |E |F |=== </wc-asciidoc-table>
ABC
Block spanRow 1 Col 3
Row 2 Col 3
DEF

Add a block title with a leading . line. Promote the last row to a footer with options="footer":

<wc-asciidoc-table> .API routes [cols="2*",options="header,footer",stripes="even"] |=== |Method |Path |GET |/users |POST |/users |Total |2 |=== </wc-asciidoc-table>
API routes
MethodPath
GET/users
POST/users
Total2

Table attributes

You can set these on the tag or in the AsciiDoc attribute list ([...]):

Comma-separated column specifiers (for example 1,2,3 or 3*). Comma-separated options: `header`, `footer`, `autowidth`. Shorthand `%header` is also supported inside `[...]`. Data format: `psv` (default), `csv`, `dsv`, or `tsv`. Override the cell separator (useful when cell text contains |). Row shading: `hover`, `even`, `odd`, `all`, or `none`. Outer border: `all`, `ends`, `sides`, or `none`. Inner lines: `all`, `rows`, `cols`, or `none`. Table width (for example `80` or `80%`). Table title. Equivalent to a `.Title` line above the attribute list.

CSV, DSV, and TSV

Set format="csv" (or use the ,=== shorthand delimiter) for comma-separated data:

<wc-asciidoc-table format="csv" options="header"> |=== Method,Path,Description GET,/health,Liveness probe POST,/deploy,Trigger deploy |=== </wc-asciidoc-table>
MethodPathDescription
GET/healthLiveness probe
POST/deployTrigger deploy

Quoted CSV fields can contain commas:

<wc-asciidoc-table format="csv" options="header"> |=== "Last, First",Role "Hopper, Grace",Admiral |=== </wc-asciidoc-table>
Last, FirstRole
Hopper, GraceAdmiral

Use format="dsv" (or :===) for colon-separated values, and format="tsv" for tabs.

Escaping pipes

If a PSV cell must contain |, escape it with a backslash or use {vbar}:

<wc-asciidoc-table> [cols="2*"] |=== |The default separator is \| |Also written as {vbar} |=== </wc-asciidoc-table>
The default separator is |Also written as |

Or change the separator entirely:

<wc-asciidoc-table cols="2*" separator="¦"> |=== ¦Pipes | are fine here ¦No escaping needed |=== </wc-asciidoc-table>

MDX-style tag

The MDX bridge also accepts PascalCase:

<AsciidocTable cols="2*" options="header"> |=== |Name |Role |Ada |Engineer |=== </AsciidocTable>

What's next