Table Columns

Number of columns

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.

For example, the syntax in the two examples below will both be converted into a table with two columns.

|===

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

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

|===
Result: Rendered table with two columns as defined by the number of cells in the first row

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

When a single number is assigned to the cols attribute, its value indicates the number of columns and each column will be the same width.

[cols="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

|===
Result: Rendered table with two columns as defined by the cols attribute

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

The number of columns can also be assigned as a comma delimited list. The number of entries in the list determines the number of columns. The comma delimited list below creates a table with four columns of equal width.

[cols="1,1,1,1"]

This syntax provides that same result:

[cols="4*"]

Now, let’s talk about that asterisk in the syntax above.

Column formatting

The AsciiDoc syntax provides a variety of ways to control the size, style and layout of content within columns. These specifiers can be applied to whole columns.

To apply a specifier to a column, you must set the cols attribute and assign it a value. A column specifier can contain any of the following components:

  • multiplier

  • align

  • width

  • style

Each component is optional.

Multiplier

The multiplier operator (*) is used when you want a specifier to apply to more than one consecutive column. If used, the multiplier must always be placed at the beginning of the specifier.

For example:

[cols="3*"] (1)
|===
|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 The table will consist of three columns, as indicated by the 3. The * operator ensures that the default layout and style will be applied to all of the columns.
Result: Rendered table with multiplier applied

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

Align column content

The alignment component allows you to horizontally or vertically align a column’s content. Content can be horizontally aligned left (<), center (^), or right (>).

To horizontally center the content in all of the columns, add the ^ operator after the multiplier.

[cols="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
|===
Result: Rendered table with horizontal, center alignment applied to all columns

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

What if you only want to center the content in the last column? Assign the default styles to the preceding columns and ^ to the last column in the list.

[cols="2*,^"]
|===
|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
|===
Result: Rendered table with horizontal, center alignment applied to last column

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

Let’s specify a different horizontal alignment for each column.

[cols="<,^,>"]
|===
|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
|===
Result: Rendered table with a different horizontal alignment for each column

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

You’ll notice that the content in the examples above is only centered on the horizontal. It can also be aligned vertically when the alignment operator is prefixed with a dot (.). Content can be vertically aligned to the top (<), middle (^), or bottom (>) of a cell.

To vertically align the content to the middle of the cells in all of the columns, add a . and then the ^ operator after the multiplier.

[cols="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
|===
Result: Rendered table with vertical, middle alignment applied to all columns

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

If you only want to align the content to the bottom of each cell in the last column, you’d assign the default styles to the preceding columns, and > to the last column in a comma separated list.

[cols="2*,.>"]
|===
|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
|===
Result: Rendered table with vertical, bottom alignment applied to last column

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

Let’s specify a different vertical alignment for each column.

[cols=".<,.^,.>"]
|===
|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
|===
Result: Rendered table with a different vertical alignment for each column

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

Finally, we’ll also horizontally center the content in the last column.

[cols=".<,.^,^.>"]
|===
|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
|===
Result: Rendered table with a different vertical alignment for each column and horizontal, center alignment in the last column

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

When both a horizontal and vertical alignment is assigned to a column, the horizontal alignment operator must precede the vertical operator.

Column width

The width component sets the width of a column. Its value can be a proportional integer (the default is 1) or a percentage (1 to 99).

[cols="1,2,6"]
|===
|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
|===
Result: Table rendered with column sizes adjusted by a proportional integer

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

When assigning percentage values to the cols attribute, you do not need to include the percent sign (%).

[cols="50,20,30"]
|===
|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
|===
Result: Table rendered with column sizes adjusted by a percentage

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

Let’s create a table with custom widths and alignments.

[cols=".<2,.^5,^.>3"]
|===
|Cell in column 1, row 1 with lots and lots and lots and lots of content
|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 and another bucket of content, and then a jelly roll of content
|===
Result: Rendered table with variable widths and alignments

Cell in column 1, row 1 with lots and lots and lots and lots of content

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 and another bucket of content, and then a jelly roll of content

Format column content

The style component must always be located at the end of the specifier. When no style name is provided column contents will be processed as regular inline text.

The column styles are described in the table below.

Style Name Value Description

AsciiDoc

a

Any block-level elements (paragraphs, delimited blocks, and block macros) may be contained within the column. The elements will be processed and converted.

Emphasis

e

Text is italicized.

Header

h

Header styles are applied to the column.

Literal

l

Column content is treated as if it were inside a literal block.

Monospaced

m

Text is rendered in monospaced font.

None (default style)

d

Text is handled like a normal paragraph. Supports all markup (i.e., inline formatting, inline macros) that is permitted in a paragraph.

Strong

s

Text is bold.

Verse

v

Column content is treated as if it were inside a verse block.

Let’s apply the header style to the first column, the monospaced style to the second, the strong style to the third, and the emphasis style to the fourth.

[cols="h,m,s,e"]
|===
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 4, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|Cell in column 4, row 2
|===
Result: Rendered table with a header, monospaced, and strong styled column

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 4, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

Cell in column 4, row 2

Specifiers can also be applied to individual cells.