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

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.