Tables

Creating Tables

A special feature of AsciiDoc is that tables are part of the standard repertoire. This is not the case in every markup language.

You create a simple table like this:

|===
|Column 1 |Column 2 |Column 3

|Cell 1.1 |Cell 1.2 |Cell 1.3
|Cell 2.1 |Cell 2.2 |Cell 2.3
|===

The result:

Column 1 Column 2 Column 3

Cell 1.1

Cell 1.2

Cell 1.3

Cell 2.1

Cell 2.2

Cell 2.3

The syntax is simple:

  • Use |=== to open and close the table.

  • Each | creates a new cell.

  • A new line in the editor starts a new row in the table.

Header Row and Column Widths

A header row is automatically created when you insert a blank line after the first row:

|===
|Name |Age |City

|Anna |28 |Berlin
|Max |35 |Munich
|===
Name Age City

Anna

28

Berlin

Max

35

Munich

With the cols attribute, you can set the column widths:

[cols="1,2,1"]
|===
|Narrow |Wide |Narrow

|A |B |C
|===

The numbers indicate the ratio of column widths. 1,2,1 means: first column 1 part, second column 2 parts, third column 1 part.

Frames and Grids

You can customize the appearance of the table with additional parameters:

Parameter Effect

frame=all/ends/sides/none

Outer frame

grid=all/cols/rows/none

Inner grid lines

stripes=even/odd/all/none

Row stripes (zebra pattern)

An example with multiple parameters:

[cols="1,2", frame=none, grid=rows, stripes=odd]
|===
|Parameter |Description

|width |Width of the table
|align |Alignment
|===
Define a text replacement in system settings (e.g., ttab) that automatically inserts a complete table structure. This saves you from repeatedly typing the basic structure.

Nested Tables

Sometimes you want to place a table inside another table – for example, to further structure related details within a cell. AsciiDoc supports this through so-called nested tables.

The challenge: the AsciiDoc parser needs to distinguish where the outer table ends and where the inner one begins. That is why the inner table uses different delimiters than the outer one.

The Rules

  • The outer table uses |=== as its boundary and | for cells, as usual.

  • The cell that will contain an inner table must have the content type a (for "AsciiDoc"). This tells the parser to interpret the cell content as full AsciiDoc.

  • The inner table uses !=== as its boundary and ! for cells – instead of |=== and |.

A Complete Example

[cols="1,2a"] 1
|=== 2
|Category |Details 3

|Fruit 4
| 5
!=== 6
!Name !Color 7

!Apple !Red 8
!Banana !Yellow
!=== 9

|Vegetables
|
!===
!Name !Color

!Carrot !Orange
!Broccoli !Green
!===

|=== 10
1 cols="1,2a" – The second column gets the type a (AsciiDoc content). Only this allows it to contain a nested table.
2 |=== – Opens the outer table.
3 |Category |Details – Header row of the outer table. The blank line after it turns it into a header.
4 |Fruit – First cell of the data row (column 1).
5 | – Second cell of the data row (column 2, type a ). The content follows from the next line.
6 !=== – Opens the inner (nested) table. The ! instead of | signals to the parser that this belongs one level deeper.
7 !Name !Color – Header row of the inner table. Here too, a blank line after it creates the header.
8 !Apple !Red – Data row of the inner table.
9 !=== – Closes the inner table.
10 |=== – Closes the outer table.

The result:

Category Details

Fruit
Name Color

Apple

Red

Banana

Yellow

Vegetables
Name Color

Carrot

Orange

Broccoli

Green

Elements at a Glance

Element Meaning

cols="1,2a"

Column widths in a 1:2 ratio. The a after the 2 sets the content type of the second column to "AsciiDoc".

|===

Opens or closes the outer table.

|

Separates cells in the outer table.

!===

Opens or closes an inner (nested) table.

!

Separates cells in the inner table.
Nested tables can quickly make a document hard to read. Use them sparingly – often a description list or an additional column is the better choice.