Build a Basic Table

A table is a delimited block that can have optional customizations, such as an ID and a title, as well as table-specific attributes, options, and roles. However, at its most basic, a table only needs columns and rows.

On this page, you’ll learn:

  • How to set up an AsciiDoc table block and its attribute list.

  • How to add columns to a table using the cols attribute.

  • How to add cells to a table and arrange them into rows.

  • How to designate a row as the table’s header row.

Create a table with two columns and three rows

In Example 1, we’ll assign the cols attribute a list of column specifiers. A column specifier represents a column.

Example 1. Set up a table with two columns
[cols="1,1"] (1) (2)
|=== (3)
1 On a new line, create an attribute list. Set the cols attribute, followed by an equals sign (=).
2 Assign a list of comma-separated column specifiers enclosed in double quotation marks (") to cols. Each column specifier represents a column.
3 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 (|===). This delimiter starts the table block.

The table in Example 1 will contain two columns because there are two comma-separated entries in the list assigned to cols. Each entry in the list is called a column specifier. A column specifier represents a column and the width, alignment, and style properties assigned to that column. When each column specifier is the same number, in this case the integer 1, all of the columns’ widths will be identical. Each column in Example 1 will be the same width regardless of how much content they contain.

Next, let’s add three rows to the table. Each row has the same number of cells. Since the table in Example 2 has two columns, each row will contain two cells. A cell starts with a vertical bar (|).

Example 2. Add three rows to the table
[cols="1,1"]
|===
|Cell in column 1, row 1 (1)
|Cell in column 2, row 1 (2)
(3)
|Cell in column 1, row 2
|Cell in column 2, row 2

|Cell in column 1, row 3
|Cell in column 2, row 3 (4)
|=== (5)
1 To create a new cell, press Shift+|. After the vertical bar (|), enter the content you want displayed in that cell.
2 On a new line, start another cell with a |. Each consecutive cell is placed in a separate, consecutive column in a row.
3 Rows are separated by one or more empty lines.
4 When you finish adding cells to your table, press Enter to go to a new line.
5 Enter the closing delimiter (|===) to end the table block.
The suggestion to start each cell on its own line and to separate rows by empty lines is merely a stylistic choice. You can enter more than one cell or all of the cells in a row on the same line since the processor creates a new cell each time it encounters a vertical bar (|).

The table from Example 2 is displayed below. It contains two columns and three rows of text positioned and styled using the default alignment, style, border, and width attribute values.

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

In addition to the cols attribute, you can identify the number of columns using a column multiplier or the table’s first row. However, the cols attribute is required to customize the width, alignment, or style of a column.

Add a header row to the table

Let’s add a header row to the table in Example 3. You can implicitly identify the first row of a table as a header row by entering all of the first row’s cells on the line directly after the opening table delimiter.

Example 3. Add a header row to the table
[cols="1,1"]
|===
|Cell in column 1, header row |Cell in column 2, header row (1)
(2)
|Cell in column 1, row 2
|Cell in column 2, row 2

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

|Cell in column 1, row 4
|Cell in column 2, row 4
|===
1 On the line directly after the opening delimiter (|===), enter all of the first row’s cells on a single line.
2 Leave the line directly after the header row empty.

The table from Example 3 is displayed below.

Cell in column 1, header row Cell in column 2, header row

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 1, row 3

Cell in column 2, row 3

Cell in column 1, row 4

Cell in column 2, row 4

A header row can also be identified by assigning header to the options attribute.