How should I format my tables?

Tables in the asciidoc format are delineated using the | (vertical pipe) to differentiate between cells. While this is simple, in a way, it also can bring in some complication, especially in terms of the readability of the raw file.

Tables are always bounded by the following characters:

|===
|===

Everything between these marks will be included in the table, with groupings of | characters marking each cell.

The simplest method for creating a row is to do this:

| cell1 | cell2 | cell3 | cell4

This will create a row with 4 columns. This can then be repeated for each row. The | characters do not need to line up to make the table look correct in the final output, but a lot of rows with different lines is difficult to read (and it is a lot of work to get all the spacing the manually line them up).

| cell1 | cell2 | cell3 | cell4
| c1r2| cell 2 row 2 |this is the third cell in row 2|c4row2
| cell1r3 | c2row3 |c3r4| fourth cell in row three

While these three rows would produce a nice table, it is difficult to read here. When using the pandoc program to convert tables, this is the type of output you will get.

Tables though can also be written with a single cell on each row:

| cell1
| cell2
| cell3
| cell4

| c1r2
| cell 2 row 2
|this is the third cell in row 2
|c4row2

This format (for the first two rows) is simpler to read, as each grouping here is one row.

A key point to using this method though is to define the number of columns for the table to ensure that the grouping for each row are always maintained. To do this, you would need to add the following line right before the beginning table marker:

[cols=4]

This will specify the number of columns. If you would like to specify the widths of the columns (relative to each other), then use this (with the relative size specified for each column):

[cols="1,2,3,4"]

In this case, each column would be relatively larger than the previous. To have them all the same, use "1,1,1,1" making sure you have a number for each column you need.

For more information about tables, look at section 7 for tables in the Syntax Guide.