Tables

Tables are delimited by |=== (a vertical bar followed by three equals signs). The number of columns in a table is determined by the number of cells found in the first non-blank line after the table delimiter (|===) or by the values assigned to the cols attribute. A new cell is created each time the processor 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.

Table with implicit column value and header row

|=== (1)
|Name of Column 1 |Name of Column 2 (2) (3)

|Cell in column 1, row 1
|Cell in column 2, row 1 (4)

|Cell in column 1, row 2 |Cell in column 2, row 2 (5)
|===

1	A table is delimited by `\|===`.
2	When a cell, marked by a vertical bar (`\|`), is placed on the line directly below the delimiter, it is interpreted as a header row.
3	The number of cells found in the header row indicates the number of columns (sets `cols` implicitly).
4	The cells in a row can be entered on separate lines.
5	The cells in a row can be entered on the same line.

The example above is published as:

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

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

Since tables are AsciiDoc block elements they can have titles, roles, IDs, as well as table-specific attributes.

Table with title, ID, cols, and options="header"

.Optional title
[#optional-id,cols="1,1,2",options="header"] (1) (2) (3) (4)
|===

|Name of Column 1
|Name of Column 2
|Name of Column 3

|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
|===

1	If assigned, an ID must be set first in the table’s attribute list.
2	The number of values assigned to `cols` indicates the number of columns, in this case, the table has three columns.
3	The proportion of each value assigned to `cols` relative to its other values indicates the width of each column. In this example, column 1 and column 2 will be half the width of column 3.
4	To make the first row a header row, assign `header` to the `options` attribute.

The example above is published as:

Optional title
Name of Column 1	Name of Column 2	Name of Column 3
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

Here’s an example of a table with a title, implicit header row, and the proportional width of the two columns set.

.CLI parameters for adding a node
[cols="1,2"]
|===
|Parameter |Description

|`--cluster`
|The IP address of a node in the existing cluster.

|`--user`
|The username for the existing cluster.

|`--password`
|The password for the existing cluster.
|===

The example above is published as:

CLI parameters for adding a node
Parameter	Description
`--cluster`	The IP address of a node in the existing cluster.
`--user`	The username for the existing cluster.
`--password`	The password for the existing cluster.

Block elements in tables

Any block-level elements, such as code blocks, lists, admonitions, etc., can be entered into a cell. However, the specifier a (which stands for AsciiDoc) must be placed on the cell, row, or column in order for them to be processed as AsciiDoc blocks. In the following example, the a specifier is placed on the cells containing block elements.

.cbq Shell Commands
[#table-cbq-shell-commands,cols="1,2,4"]
|===
|Shell Command |Arguments |Description and Examples

|`\SET`
|`parameter=prefix:variable name`
a|
Sets the top most value of the stack for the given variable with the specified value.

Variables can be of the following types:

[#set-var-types]
* Query parameters
* Session variables
* User-defined
* Pre-defined and named parameters.

|`\PUSH`
|`parameter value`
a|
Pushes the specified value on to the given parameter stack.

----
cbq> \PUSH -args  [8];
----

.Resulting variable stack
----
cbq> \SET;
 Query Parameters :
 Parameter name : args
 Value : [[6,7] [8] [8]]
...
cbq>
----
|===

The example above is published as:

cbq Shell Commands
Shell Command	Arguments	Description and Examples
`\SET`	`parameter=prefix:variable name`	Sets the top most value of the stack for the given variable with the specified value. Variables can be of the following types: Query parameters Session variables User-defined Pre-defined and named parameters.
`\PUSH`	`parameter value`	Pushes the specified value on to the given parameter stack. cbq> \PUSH -args [8]; Resulting variable stack cbq> \SET; Query Parameters : Parameter name : args Value : [[6,7] [8] [8]] ... cbq>

Column and row spans

The span factor is the number of columns or rows, including the starting row or column, the cell should span.

To have a cell span multiple columns, place the span factor and + operator directly before the | of the starting cell.
To span multiple rows, place a dot (.) directly before the span factor and + operator.

|===

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

3+|Content in a single cell that spans columns 1, 2, and 3

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

.2+|Content in a single cell that spans rows 4 and 5
|Cell in column 2, row 4
|Cell in column 3, row 4

|Cell in column 2, row 5
|Cell in column 3, row 5
|===

The example above is published as:

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Content in a single cell that spans columns 1, 2, and 3

Cell in column 1, row 3

Cell in column 2, row 3

Cell in column 3, row 3

Content in a single cell that spans rows 4 and 5

Cell in column 2, row 4

Cell in column 3, row 4

Cell in column 2, row 5

Cell in column 3, row 5

Table widths

The default width for a table is set to 100%. There are three ways to override this default:

Set the width explicitly (in percentage) using the width attribute (e.g., width=50%)
Set the autowidth option so that table only expands to accommodate the contents (e.g., %autowidth)
Assign a role to the table to allow the width to be controlled by CSS using presets (e.g., .narrow)

For more information, see the Asciidoctor table width documentation.

Table attributes and options

There are a lot of AsciiDoc table attributes, options, and specifiers. For more examples and information, see the Asciidoctor table documentation.