Asciidoctor User Manual

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 converted to a table with two columns.

When a single number is assigned to the cols attribute, its value indicates the number of columns. Each column will be the same width. However, 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.

This syntax provides that same result:

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

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:

Each component is optional.

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:

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.

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 a comma separated list.

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

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.

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.

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

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

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

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).

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

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

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.

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.

Specifiers can also be applied to individual cells.

In addition to sharing many of the column specifier capabilities, cell specifiers allow cells to span rows and columns. Like a column specifier, a cell specifier is made up of components. These components, listed and defined below, are all optional.

A cell specifier is prefixed directly to the cell delimiter (|) preceding the content you want to customize.

The span component can duplicate a cell or have it span multiple rows or columns.

To duplicate a cell in multiple, consecutive columns, prefix the | with the multiplication factor and the * operator.

To have a cell span multiple, consecutive columns, prefix the | with the span factor and the + operator.

If you want to have a cell span multiple, consecutive rows, prefix the span factor with a dot (.).

Of course you can combine spanning over columns and rows. The number before the dot (.) is the number of columns to span and the number after the dot (.) is the number of rows to span.

The alignment component for cells works the same as the column specifier alignment component.

The style component can also be applied to individual cells. For example, you can apply the AsciiDoc element styles to an individual cell by prefixing the vertical bar with an a.

Source code listing can be placed inside cells by using the listing syntax.

For the grand finale, let’s apply a variety of specifiers to individual cells.

The first row of a table is promoted to a header row if the header option is set (either explicitly or implicitly).

You can enable the header option by adding the header keyword to the comma-separated list of values in the options attribute on the table. You can also enable the header option by adding the %header directive to the table style (the first positional attribute).

In the example below, the table has an attribute list containing an options attribute that includes the header option.

Alternately, you can define the header row based on how you layout the table. Asciidoctor use the following conventions to determine when the first row should become the header row:

As seen in the result of the example below, if all of these rules hold, then the first row of the table is treated as a header.

If you want to suppress this implicit behavior of promoting the first row to a header row, set the option value noheader (or add the %noheader directive to the table style).

Notice that when the implicit method of assigning the header row is used, it’s not necessary to set the cols attribute. That’s because the number of columns are determined by the number of cells in the first line if the cols attribute is absent.

The last row of a table can be styled as a footer by adding the footer keyword to the options attribute.

By default, a table will span the width of the content area. To constrain the width of the table to a fixed value, set the width attribute in the table’s attribute list. The width is an integer percentage value ranging from 1 to 100. The % sign is optional.

Alternately, you can make the width fit the content by setting the autowidth option. The columns inherit this setting, so individual columns will also be sized according to the content.

If you want each column to have an automatic width, but want the table to span the width of the content area, add the stretch role to the table or set the width attribute to 100%.

If you want to apply autowidth only to certain columns, use the special value ~ as the width of the column. In this case, width values are assumed to be a percentage value (i.e., 100-based).

The borders on a table are controlled using the frame and grid attributes. You can combine these two attributes to achieve a variety of border styles for your tables.

Starting with Asciidoctor 2.0, the rows in the body of a table are not shaded. You can configure the rows to be striped (as in zebra stripes) using an attribute. Use the stripes table attribute to configure the stripes for a single table. Use the table-stripes document attribute to configure stripes for all tables.

Striping is done by adding a background color to the specified rows. The stripes attribute accepts the following values:

In the following example, the stripes are enabled for even rows in the table body (the row that contains A2, B2, and C2).

Under the covers, the stripes attribute applies the CSS class stripes-<value> (e.g., stripes-none) to the table tag. As a shorthand, you can simply apply the CSS class to the table directly using a role.

If you want to apply stripes to all tables in the document, set the table-stripes attribute in the document header. You can still override this setting per table.

In the HTML output, table striping is done using CSS and thus depends on the stylesheet to supply the necessary styles. The default stylesheet for Asciidoctor includes these styles.

A table can be displayed in landscape (rotated 90 degrees counterclockwise) using the rotate option (preferred):

or the orientation attribute:

Currently, this is only implemented by the DocBook backend (it sets the attribute orient="land").

Table cells marked with the AsciiDoc table style (a) support nested tables in addition to normal block content. To distinguish the inner table from the enclosing one, you need to use !=== as the table delimiter and a cell separator that differs from that used for the enclosing table. The default cell separator for a nested table is !, though you can choose another character by defining the separator attribute on the table.

The following example contains a nested table in the last cell. Notice the nested table has its own format, independent of that of the outer table:

We recommend using nested tables sparingly. There’s usually a better way to present the information.

If you specify a title on a table, the title will be used as part of the table’s caption. Adding a title also designates the table as a formal table.

By default, the title of a formal table is prefixed with the label Table <n>. followed by a space, where <n> is the 1-based index of all formal tables in the document.

You can customize the caption label by specifying the caption attribute. (Don’t let the name of the attribute mislead you. The caption attribute only sets the caption’s label, not the whole caption line).

If you want the caption of the table to only consist of the caption label, use the following syntax:

Alternately, you can write is as follows:

If you want to exclude the caption label altogether, simply assign a blank value to the caption attribute.

Alternatively, you can disable the caption label for tables globally by undefining the table-caption document attribute.

The parser scans for the cell separator to partition cells before it processes the cell text. So even if you try to hide the cell separator using an inline passthrough, the parser will see it. If the cell contain contains the cell separator, you must escape that character. There are three ways to escape it:

Unless you do one of these things, the cell separator will be interpreted as a cell boundary.

Consider the following example, which escapes the cell separator using a leading backslash:

This table will render as follows:

Notice that the pipe character appears without the leading backslash (i.e., unescaped) in the rendered result.

An alternative is to use the {vbar} attribute reference as a substitute. This approach produces the same result as the previous example.

Escaping each cell separator character that appears in the content of a cell can be tedious. There are also times when you can’t or don’t want to modify the cell content (perhaps because it is being included from another file). To address these cases, AsciiDoc allows you to override the cell separator.

The cell separator is controlled using the separator attribute on the table block. You’ll want to select a character that will never be used for content. A good candidate is the broken bar, or ¦.

Here’s the previous example rewritten using a custom separator.

Notice that it’s no longer necessary to escape the pipe character in the content of the table cells. You can safely use the original cell separator in the cell content and not worry about it being interpreted as the boundary of a cell.

Tables can also be populated from data formatted as delimiter-separated values (i.e., data tables). In contrast with the PSV format, in which the delimiter is placed in front of each cell value, the delimiter in a delimiter-separated format (CSV, TSV, DSV) is placed between the cell values (called a separator) and does not accept a cell formatting spec. Each line of data is assumed to represent a single row, though you’ll learn that’s not a strict rule. How the table data gets interpreted is controlled by the format and separator attributes on the table.

Let’s consider an example of using comma-separated values (CSV) to populate an AsciiDoc table with data. To instruct the processor to read the data as CSV, set the value of the format attribute on the table to csv. When the format attribute is set to csv, the default data separator is a comma (,), as seen in the table below.

This feature is particularly useful when you want to populate a table in your manuscript from data stored in a separate file. You can do so using the include directive between the table delimiters, as shown here:

If your data is separated by tabs instead of commas, set the format to tsv (tab-separated values) instead.

Now let’s consider an example of using delimited data (DSV) to populate an AsciiDoc table with data. To instruct the processor to read the data as DSV, set the value of the format attribute on the table to dsv. When the format attribute is set to dsv, the default data separator is a colon (:), as seen in the table below.