Chapter 23. Tables

The AsciiDoc table syntax looks and behaves like other delimited block types and supports standard block configuration entries. Formatting is easy to read and, just as importantly, easy to enter.

23.1. Example tables

Table 23.1. Simple table










AsciiDoc source. 

|1 |2 |A
|3 |4 |B
|5 |6 |C

Table 23.2. Columns formatted with strong, monospaced and emphasis styles

Columns 2 and 3

footer 1

footer 2

footer 3


Item 1

Item 1


Item 2

Item 2


Item 3

Item 3


Item 4

Item 4

AsciiDoc source. 

.An example table
|      2+|Columns 2 and 3
|1       |Item 1  |Item 1
|2       |Item 2  |Item 2
|3       |Item 3  |Item 3
|4       |Item 4  |Item 4
|footer 1|footer 2|footer 3

Table 23.3. Horizontal and vertical source data

Date Duration Avg HR Notes




Worked out MSHR (max sustainable heart rate) by going hard for this interval.




Back-to-back with previous interval.




Moderately hard interspersed with 3x 3min intervals (2min hard + 1min really hard taking the HR up to 160).

Short cells can be entered horizontally, longer cells vertically. The default behavior is to strip leading and trailing blank lines within a cell. These characteristics aid readability and data entry.

AsciiDoc source. 

.Windtrainer workouts
|Date |Duration |Avg HR |Notes

|22-Aug-08 |10:24 | 157 |
Worked out MSHR (max sustainable heart rate) by going hard
for this interval.

|22-Aug-08 |23:03 | 152 |
Back-to-back with previous interval.

|24-Aug-08 |40:00 | 145 |
Moderately hard interspersed with 3x 3min intervals (2min
hard + 1min really hard taking the HR up to 160).


Table 23.4. A table with externally sourced CSV data

IDCustomer NameContact NameCustomer AddressPhone


Around the Horn

Thomas Hardy

120 Hanover Sq. London

(171) 555-7788


Berglunds snabbkop

Christina Berglund

Berguvsvagen 8 Lulea

0921-12 34 65


Blauer See Delikatessen

Hanna Moos

Forsterstr. 57 Mannheim



Blondel pere et fils

Frederique Citeaux

24, place Kleber Strasbourg


Bolido Comidas preparadas

Martin Sommer

C/ Araquil, 67 Madrid

(91) 555 22 82


Bon app'

Laurence Lebihan

12, rue des Bouchers Marseille


Bottom-Dollar Markets

Elizabeth Lincoln

23 Tsawassen Blvd. Tsawassen

(604) 555-4729


B’s Beverages

Victoria Ashworth

Fauntleroy Circus London

(171) 555-1212


Cactus Comidas para llevar

Patricio Simpson

Cerrito 333 Buenos Aires

(1) 135-5555

AsciiDoc source. 

ID,Customer Name,Contact Name,Customer Address,Phone

Table 23.5. Cell spans, alignments and styles











AsciiDoc source. 

|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
|9 2+>|10

23.2. Table input data formats

AsciiDoc table data can be psv, dsv or csv formatted. The default table format is psv.

AsciiDoc psv (Prefix Separated Values) and dsv (Delimiter Separated Values) formats are cell oriented — the table is treated as a sequence of cells — there are no explicit row separators.

  • psv prefixes each cell with a separator whereas dsv delimits cells with a separator.
  • psv and dsv separators are Python regular expressions.
  • The default psv separator contains cell specifier related named regular expression groups.
  • The default dsv separator is :|\n (a colon or a new line character).
  • psv and dsv cell separators can be escaped by preceding them with a backslash character.

Here are four psv cells (the second item spans two columns; the last contains an escaped separator):

|One 2+|Two and three |A \| separator character

csv is the quasi-standard row oriented Comma Separated Values (CSV) format commonly used to import and export spreadsheet and database data.

23.3. Table attributes

Tables can be customized by the following attributes:

psv (default), dsv or csv (See Table Data Formats).
The cell separator. A Python regular expression (psv and dsv formats) or a single character (csv format).
Defines the table border and can take the following values: topbot (top and bottom), all (all sides), none and sides (left and right sides). The default value is all.
Defines which ruler lines are drawn between table rows and columns. The grid attribute value can be any of the following values: none, cols, rows and all. The default value is all.
Use the align attribute to horizontally align the table on the page (works with HTML outputs only, has no effect on DocBook outputs). The following values are valid: left, right, and center.
Use the float attribute to float the table left or right on the page (works with HTML outputs only, has no effect on DocBook outputs). Floating only makes sense in conjunction with a table width attribute value of less than 100% (otherwise the table will take up all the available space). float and align attributes are mutually exclusive. Use the unfloat::[] block macro to stop floating.
Use the halign attribute to horizontally align all cells in a table. The following values are valid: left, right, and center (defaults to left). Overridden by Column specifiers and Cell specifiers.
Use the valign attribute to vertically align all cells in a table. The following values are valid: top, bottom, and middle (defaults to top). Overridden by Column specifiers and Cell specifiers.
The options attribute can contain comma separated values, for example: header, footer. By default header and footer rows are omitted. See attribute options for a complete list of available table options.

The cols attribute is a comma separated list of column specifiers. For example cols="2<p,2*,4p,>".

  • If cols is present it must specify all columns.
  • If the cols attribute is not specified the number of columns is calculated as the number of data items in the first line of the table.
  • The degenerate form for the cols attribute is an integer specifying the number of columns e.g. cols=4.
The width attribute is expressed as a percentage value ("1%""99%"). The width specifies the table width relative to the available width. HTML backends use this value to set the table width attribute. It’s a bit more complicated with DocBook, see the DocBook table widths sidebar.
The filter attribute defines an external shell command that is invoked for each cell. The built-in asciidoc table style is implemented using a filter.

23.4. Column Specifiers

Column specifiers define how columns are rendered and appear in the table cols attribute. A column specifier consists of an optional column multiplier followed by optional alignment, width and style values and is formatted like:

  • All components are optional. The multiplier must be first and the style last. The order of <align> or <width> is not important.
  • Column <width> can be either an integer proportional value (1…) or a percentage (1%…100%). The default value is 1. To ensure portability across different backends, there is no provision for absolute column widths (not to be confused with output column width markup attributes which are available in both percentage and absolute units).
  • The <align> column alignment specifier is formatted like:


    Where <horizontal> and <vertical> are one of the following characters: <, ^ or > which represent left, center and right horizontal alignment or top, middle and bottom vertical alignment respectively.

  • A <multiplier> can be used to specify repeated columns e.g. cols="4*<" specifies four left-justified columns. The default multiplier value is 1.
  • The <style> name specifies a table style to used to markup column cells (you can use the full style names if you wish but the first letter is normally sufficient).
  • Column specific styles are not applied to header rows.

23.5. Cell Specifiers

Cell specifiers allow individual cells in psv formatted tables to be spanned, multiplied, aligned and styled. Cell specifiers prefix psv | delimiters and are formatted like:

  • <span> specifies horizontal and vertical cell spans (+ operator) or the number of times the cell is replicated (* operator). <span> is formatted like:


    Where <colspan> and <rowspan> are integers specifying the number of columns and rows to span.

  • <align> specifies horizontal and vertical cell alignment an is the same as in column specifiers.
  • A <style> value is the first letter of table style name.

For example, the following psv formatted cell will span two columns and the text will be centered and emphasized:

`2+^e| Cell text`

23.6. Table styles

Table styles can be applied to the entire table (by setting the style attribute in the table’s attribute list) or on a per column basis (by specifying the style in the table’s cols attribute). Table data can be formatted using the following predefined styles:

The default style: AsciiDoc inline text formatting; blank lines are treated as paragraph breaks.
Like default but all text is emphasised.
Like default but all text is in a monospaced font.
Like default but all text is bold.
Apply the same style as the table header. Normally used to create a vertical header in the first column.
With this style table cells can contain any of the AsciiDoc elements that are allowed inside document sections. This style runs asciidoc(1) as a filter to process cell contents. See also Docbook table limitations.
No text formatting; monospaced font; all line breaks are retained (the same as the AsciiDoc LiteralBlock element).
All line breaks are retained (just like the AsciiDoc verse paragraph style).

23.7. Markup attributes

AsciiDoc makes a number of attributes available to table markup templates and tags. Column specific attributes are available when substituting the colspec cell data tags.

DocBook backend only. Specifies table column absolute width units. Defaults to *.
DocBook backend only. The nominal output page width in pageunit units. Used to calculate CALS tables absolute column and table widths. Defaults to 425.
Integer value calculated from width and pagewidth attributes. In pageunit units.
Table width expressed as a percentage of the available width. Integer value (0..100).
Integer value calculated from cols column width, width and pagewidth attributes. In pageunit units.
Column width expressed as a percentage of the table width. Integer value (0..100).
Total number of table columns.
Total number of table rows.
Horizontal cell content alignment: left, right or center.
Vertical cell content alignment: top, bottom or middle.
colnumber, colstart
The number of the leftmost column occupied by the cell (1…).
The number of the rightmost column occupied by the cell (1…).
Number of columns the cell should span.
Number of rows the cell should span (1…).
Number of additional rows the cell should span (0…).

23.8. Nested tables

An alternative psv separator character ! can be used (instead of |) in nested tables. This allows a single level of table nesting. Columns containing nested tables must use the asciidoc style. An example can be found in ./examples/website/newtables.txt.

23.9. DocBook table limitations

Fully implementing tables is not trivial, some DocBook toolchains do better than others. AsciiDoc HTML table outputs are rendered correctly in all the popular browsers — if your DocBook generated tables don’t look right compare them with the output generated by the AsciiDoc xhtml11 backend or try a different DocBook toolchain. Here is a list of things to be aware of:

  • Although nested tables are not legal in DocBook 4 the FOP and dblatex toolchains will process them correctly. If you use a2x(1) you will need to include the --no-xmllint option to suppress DocBook validation errors.


    In theory you can nest DocBook 4 tables one level using the entrytbl element, but not all toolchains process entrytbl.

  • DocBook only allows a subset of block elements inside table cells so not all AsciiDoc elements produce valid DocBook inside table cells. If you get validation errors running a2x(1) try the --no-xmllint option, toolchains will often process nested block elements such as sidebar blocks and floating titles correctly even though, strictly speaking, they are not legal.
  • Text formatting in cells using the monospaced table style will raise validation errors because the DocBook literal element was not designed to support formatted text (using the literal element is a kludge on the part of AsciiDoc as there is no easy way to set the font style in DocBook.
  • Cell alignments are ignored for verse, literal or asciidoc table styles.