Add Columns to a Table
The number of columns in a table is specified by the cols attribute or by the number of cells found in the first non-empty line after the opening table delimiter (|===).
Specify the number of columns with the cols attribute
The cols attribute is set in the attribute list on a table block.
It accepts a comma-separated list of column specifiers.
Each column specifier represents a column and the width, alignment, and style properties assigned to that column.
A column specifier is commonly represented by a number, but in some cases, can be represented by a symbol or letter.
In Example 1, cols is assigned a list of four numeric column specifiers.
[cols="1,1,1,1"]In Example 1, the value assigned to cols contains four column specifiers.
The number of entries in the value’s list determines the number of columns in the table.
That means the table in the above example will contain four columns.
When the specifier is a number, such as 1 or 50, the integer represents the width of the column in proportion to the other columns in the table.
In Example 1, each column will be the same width because the integer in each specifier is the same.
Let’s look at the column specifiers in Example 2 and compare it to Example 1.
[cols="3,3,3,3"]Both Example 1 and Example 2 will produce tables with four columns of equal width.
Let’s use the cols value in Example 2 to create a table.
[cols="3,3,3,3"] (1)
|=== (2)
|Column 1 |Column 2 |Column 3 |Column 4 (3)
(4)
|Cell in column 1 (5)
|Cell in column 2
|Cell in column 3
|Cell in column 4
|=== (6)| 1 | In an attribute list, set the cols attribute, followed by an equals sign (=), and then a list of comma-separated column specifiers enclosed in double quotation marks ("). |
| 2 | On the line directly after the attribute list, enter the opening table delimiter.
A table delimiter is one vertical bar followed by three equals signs (|===). |
| 3 | A table cell is specified by a vertical bar (|).
Since four consecutive cells are entered on the first line directly after the delimiter, this row is implicitly set as the table’s header row. |
| 4 | Insert an empty line after the header row. |
| 5 | The cells for the next row can be entered on a single line or on individual lines. |
| 6 | On a new line after the last cell of the last row, enter another table delimiter (|===) to close the table block. |
Example 3 creates the table displayed below.
| Column 1 | Column 2 | Column 3 | Column 4 |
|---|---|---|---|
Cell in column 1 |
Cell in column 2 |
Cell in column 3 |
Cell in column 4 |
As specified, the table includes four columns of equal width, a header row, and a regular row.
Since all of the columns in Example 3 are assigned the same width via their column specifiers (i.e., 3), the number of columns could be specified with a column multiplier.
Or, you could adjust the width of an individual column by increasing the numerical value of its specifier.
Using a column multiplier
A column multiplier allows you to apply the same width, horizontal alignment, vertical alignment, and content style to multiple, consecutive columns in a table.
A multiplier consists of an integer (<n>) and an asterisk (*).
The integer represents the number of consecutive columns to be added to the table.
The asterisk (*) is called the multiplier operator and is placed directly after the integer (<n>*).
The operator tells the converter to interpret the integer as part of a column multiplier instead of a column specifier.
For example, let’s rewrite the value of [cols="5,5,5"] as a column multiplier.
[cols="3*"] (1)| 1 | Assign an integer to cols that represents the number of columns in the table.
Enter the multiplier operator (*) directly after the integer. |
The integer 3, combined with the * operator, indicates that the table will contain three columns of equal width.
You can use a multiplier in a comma-separated list with column specifiers, too. In Example 5, the first column is represented by a column specifier, and the next three columns are represented by a multiplier.
[cols="5,3*"]
|===
|Column 1 |Column 2 |Column 3 |Column 4
|Cell in column 1
|Cell in column 2
|Cell in column 3
|Cell in column 4
|===As shown below, Example 5 creates a table containing a wide first column followed by three columns of equal width.
| Column 1 | Column 2 | Column 3 | Column 4 |
|---|---|---|---|
Cell in column 1 |
Cell in column 2 |
Cell in column 3 |
Cell in column 4 |
Alignment and style column operators
AsciiDoc provides operators that control the positioning and style of column content when the cols attribute is set.
A column specifier or multiplier can contain these optional operators for one or more of the following properties:
Many of these operators can be applied to individual cells as well.
Specify the number of columns using the first row
When all of the columns in a table use the default width, alignment, and style values, you don’t need to set the cols attribute.
Instead, you can implicitly declare the number of columns by entering all of the first row’s cells on the same line.
The processor will derive the number columns from the number of cells in this row.
Example 6 uses its first row to indicate that it has three columns.
|===
(1)
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 (2)
|Cell in column 1, row 2 (3)
|Cell in column 2, row 2
|Cell in column 3, row 2
|===| 1 | After the opening delimiter, insert an empty line before the first row, unless you want the first row to be treated as header row. |
| 2 | Enter all of the first row’s cells on a single line. Each cell represents one column. |
| 3 | The cells in subsequent rows don’t need to be entered on a single line. |
The table in Example 6 has three columns since its first row contains three cells.
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 |