Tables

Tables are one of the most intricate, yet refined areas of the AsciiDoc syntax. Armed with a bit of knowledge, you should discover that they are both easy to create and easy to read in raw form. Yet, under all that simplicity, they are remarkably sophisticated.

Basic, default table structure

A table is delimited by a vertical bar and three equal signs (|===) and made up of cells. A cell is specified by a vertical bar (|). The default table data format is PSV (Prefix Separated Values); that means the processor creates a new cell each time it encounters a vertical bar. Cells are grouped into rows. Each row must share the same number of cells, taking into account any column or row spans. Then, each consecutive cell in a row is placed in a separate column.

The table example below consists of two columns and three rows.

Basic table
|=== (1)
(2)
| Cell in column 1, row 1 | Cell in column 2, row 1  (3)
(4)
| Cell in column 1, row 2 | Cell in column 2, row 2

| Cell in column 1, row 3 | Cell in column 2, row 3

|=== (1)
1 The table’s content boundaries are defined by a vertical bar followed by three equal signs (|===).
2 Inserting a blank line before the first row is a trick to ensure the first row is not treated as the table header.
3 A new cell is marked by a vertical bar (|).
4 Rows can optionally be separated by any number of blank lines.
Result: Rendered basic table

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 1, row 3

Cell in column 2, row 3

Like with all blocks, you can add a role to a table using the role attribute. The role attribute becomes a CSS class when converted to HTML. The preferred shorthand for assigning the role attribute is to put the role name in the first position of the block attribute list prefixed with a . character, as shown here:

[.rolename]
|===

| Cell in column 1, row 1 | Cell in column 2, row 1 | Cell in column 3, row 1

| Cell in column 1, row 2 | Cell in column 2, row 2 | Cell in column 3, row 2

|===

Leading and trailing spaces around cell content is stripped and, therefore, doesn’t affect the table’s layout when rendered.

Table Caption

If you specify a title on a table, the title will be used as part of the table’s caption. Adding a title also designates the table as a formal table.

By default, the title of a formal table is prefixed with the label Table <n>. followed by a space, where <n> is the 1-based index of all formal tables in the document.

.A formal table
|===
|Name of Column 1 |Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
A table with a title
Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

You can customize the caption label by specifying the caption attribute. If you want a space between the label and the title, you must add a trailing space to the value of the caption attribute. (Don’t let the name of the attribute mislead you. The caption attribute only sets the caption’s label, not the whole caption line).

[caption="Table A. "]
.A formal table
|===
|Name of Column 1 |Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
Table A. A formal table
Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

If you want to exclude the caption label altogether, simply assign a blank value to the caption attribute.

[caption=]
.A formal table
|===
|Name of Column 1 |Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
A formal table
Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Alternatively, you can disable the caption label for tables globally by undefining the table-caption document attribute.

:table-caption!: