Tables are the most complex AsciiDoc elements and this section is quite long. [1]
![[Note]](../../../../../asciidoc/images/icons/note.png){kind=icon} | |
AsciiDoc generates nice HTML tables, but the current crop of DocBook toolchains render tables with varying degrees of success. Use tables only when really necessary. |
The following annotated examples are all you'll need to start creating your own tables.
The only non-obvious thing you'll need to remember are the column stop characters:
- Backtick (`) — align left.
- Single quote (') — align right.
- Period (.) — align center.
Simple table:
`---`--- 1 2 3 4 5 6 --------
Output:
| 1 | 2 |
| 3 | 4 |
| 5 | 6 |
Table with title, header and footer:
.An example table [grid="all"] '---------.-------------- Column 1 Column 2 ------------------------- 1 Item 1 2 Item 2 3 Item 3 ------------------------- 6 Three items -------------------------
Output:
Four columns totaling 15% of the pagewidth, CSV data:
[frame="all"] ````~15 1,2,3,4 a,b,c,d A,B,C,D ~~~~~~~~ ````~ 1,2,3,4 a,b,c,d A,B,C,D ~~~~~~~~ ````~ 1,2,3,4 a,b,c,d A,B,C,D short,a bit longer, much longer than 1st, "Oh dear, this one is extreme long" ~~~~~~~~ `10`15`25`~ 1,2,3,4 a,b,c,d A,B,C,D ~~~~~~~~ `5`10`15`25~40 1,2,3,4 a,b,c,d A,B,C,D ~~~~~~~~
Output:
| 1 | 2 | 3 | 4 |
| a | b | c | d |
| A | B | C | D |
| 1 | 2 | 3 | 4 |
| a | b | c | d |
| A | B | C | D |
| 1 | 2 | 3 | 4 |
| a | b | c | d |
| A | B | C | D |
| short | a bit longer | much longer than 1st | Oh dear, this one is extreme long |
| 1 | 2 | 3 | 4 |
| a | b | c | d |
| A | B | C | D |
| 1 | 2 | 3 | 4 |
| a | b | c | d |
| A | B | C | D |
A table with a numeric ruler and externally sourced CSV data:
[frame="all", grid="all"] .15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ID,Customer Name,Contact Name,Customer Address,Phone ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include::customers.csv[] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Text based multi-row tables are not grouped as you wished, but the generated table does not look bad either.
`----------`-----------------------------`-------------------------------
Key Arguments Event
to callback
------------------------------------------------------------------------
Final parser handle Document parsing completed
Start parser handle, Start tag found
element name,
attributes
End parser handle, End tag found
element name
------------------------------------------------------------------------| Key | Arguments | Event |
|---|---|---|
| to callback | ||
| Final | parser handle | Document parsing completed |
| Start | parser handle, | Start tag found |
| element name, | ||
| attributes | ||
| End | parser handle, | End tag found |
| element name |
[1] The current table syntax is overly complicated and unwieldy to edit, hopefully a more usable syntax will appear in future versions of AsciiDoc.
