Creating a table with Asciidoctor is a breeze. The syntax is very clear and the HTML output shows a very nice looking table. But there is also a lot of configuration we can do when we define a table. For example by default all columns are left aligned, but we can change this to have values centered or right aligned in columns. We can even set the vertical alignment for columns. And if this is not enough we can change the horizontal and vertical alignment per cell.

Let's start with a simple table with three columns. We want the first column to be centered, the middle column to be left aligned and the last column should be right aligned. To achieve this we must configure the cols attribute for our table definition. We use the following symbols to define the alignment:

  • <: left align values (default)
  • >: right align values
  • ^: center values

We create a new Asciidoctor file with the following contents:

// File: table.adoc

// We define a table with 3-columns.
// First column is centered,
// second column is left aligned and
// third column is right aligned.

[cols="^,<,>", options="header"]
|===

| Name
| Description
| Version

| Asciidoctor
| Awesome way to write documentation
| 1.5.0
|===

When we create HTML output from this source we get the following output:

We have now defined the horizontal alignment. To include vertical alignment we must add dot (.) to the horizontal alignment value and then the vertical alignment value. The following vertical alignment values can be used:

  • <: top align values (default)
  • >: bottom align values
  • ^: center values

In the following sample Asciidoctor file we add vertical alignment configuration to our previous table:

// File: table.adoc

// We define a table with 3-columns.
// First column is centered and bottom aligned,
// second column is left and top aligned and
// third column is right aligned and centered vertically.

[cols="^.>,<.<,>.^", options="header"]
|===

| Name
| Description
| Version

| Asciidoctor
| Awesome way to write documentation
| 1.5.0
|===

We get the following HTML table when we process that source file:

Finally we can alter the horizontal and vertical alignment per cell. We use the alignment configuration symbols before the pipe symbol (|) of a cell definition. This overrules any alignment configuration set in the cols definition. In the next Asciidoctor file we combine all these settings for a table:

// File: table.adoc

// We define a table with 3-columns.
// The row header has all cell values
// centered.
// The first table row cell is right aligned.
// The last table row cell is horizontal
// and vertical centered.

[cols="3*", options="header"]
|===

^| Name
^| Description
^| Version

>| Asciidoctor
| Awesome way to write documentation
^.^| 1.5.0
|===

And when we look at the output we see all alignment configuration applied to our table:

Written with Asciidoctor 1.5.0.

Original article

shadow-left