AsciiDoc New tables

New in version 8.3.0

I’ve finally come up with a new tables syntax that I’m happy with and can at last remove this footnote from the User Guide: “The current table syntax is overly complicated and unwieldy to edit, hopefully a more usable syntax will appear in future versions of AsciiDoc.”

Update

The following additions were made at AsciiDoc 8.4.4:

Cell column and row spanning.
Styles can be applied per cell.
Vertical cell alignment can be applied to columns and cells.

See the examples at the end of this document.

At first glance it doesn’t look much different to the old syntax but it’s a lot more flexible, easier to enter and supports a lot of column styles (for example the asciidoc style supports AsciiDoc block and inline elements). The old tables syntax has been deprecated but is currently still processed. Here are some examples of AsciiDoc new tables:

Table 1. Simple table
1	2	A
3	4	B
5	6	C

AsciiDoc source

[width="15%"]
|=======
|1 |2 |A
|3 |4 |B
|5 |6 |C
|=======

Table 2. Table with title, header and footer
Column 1	Column 2
6	Three items
1	Item 1
2	Item 2
3	Item 3

AsciiDoc source

.An example table
[width="40%",frame="topbot",options="header,footer"]
|======================
|Column 1 |Column 2
|1        |Item 1
|2        |Item 2
|3        |Item 3
|6        |Three items
|======================

Table 3. Columns formatted with strong, monospaced and emphasis styles
	Columns 2 and 3
footer 1	`footer 2`	footer 3
1	`Item 1`	Item 1
2	`Item 2`	Item 2
3	`Item 3`	Item 3
4	`Item 4`	Item 4

AsciiDoc source

.An example table
[width="50%",cols=">s,^2m,^2e",frame="topbot",options="header,footer"]
|==========================
|      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 4. A table with externally sourced CSV data
ID	Customer Name	Contact Name	Customer Address	Phone
AROUT	Around the Horn	Thomas Hardy	120 Hanover Sq. London	(171) 555-7788
BERGS	Berglunds snabbkop	Christina Berglund	Berguvsvagen 8 Lulea	0921-12 34 65
BLAUS	Blauer See Delikatessen	Hanna Moos	Forsterstr. 57 Mannheim	0621-08460
BLONP	Blondel pere et fils	Frederique Citeaux	24, place Kleber Strasbourg	88.60.15.31
BOLID	Bolido Comidas preparadas	Martin Sommer	C/ Araquil, 67 Madrid	(91) 555 22 82
BONAP	Bon app'	Laurence Lebihan	12, rue des Bouchers Marseille	91.24.45.40
BOTTM	Bottom-Dollar Markets	Elizabeth Lincoln	23 Tsawassen Blvd. Tsawassen	(604) 555-4729
BSBEV	B’s Beverages	Victoria Ashworth	Fauntleroy Circus London	(171) 555-1212
CACTU	Cactus Comidas para llevar	Patricio Simpson	Cerrito 333 Buenos Aires	(1) 135-5555

AsciiDoc source

 [format="csv",cols="^1,4*2",options="header"]
 |===================================================
 ID,Customer Name,Contact Name,Customer Address,Phone
 include::customers.csv[]
 |===================================================

Table 5. DVS formatted table
root	x	0	0	root	/root	/bin/bash
daemon	x	1	1	daemon	/usr/sbin	/bin/sh
bin	x	2	2	bin	/bin	/bin/sh
sys	x	3	3	sys	/dev	/bin/sh
sync	x	4	65534	sync	/bin	/bin/sync
games	x	5	60	games	/usr/games	/bin/sh

AsciiDoc source

[width="70%",format="dsv"]
|====================================
root:x:0:0:root:/root:/bin/bash
daemon:x:1:1:daemon:/usr/sbin:/bin/sh
bin:x:2:2:bin:/bin:/bin/sh
sys:x:3:3:sys:/dev:/bin/sh
sync:x:4:65534:sync:/bin:/bin/sync
games:x:5:60:games:/usr/games:/bin/sh
|====================================

Table 6. Horizontal and vertical source data
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).

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
[width="80%",cols="3,^2,^2,10",options="header"]
|=========================================================
|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 7. Default and verse styles
Default paragraphs	Centered verses
Per id. Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.	Per id. Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.

AsciiDoc source

[cols=",^v",options="header"]
|===================================
|Default paragraphs |Centered verses
2*|Per id.

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
|===================================

Table 8. Horizontal and vertical headings
	West	Central	East	Total
Q1	270	292	342	904
Q2	322	276	383	981
Q3	298	252	274	824
Q4	344	247	402	993

AsciiDoc source

.Horizontal and vertical headings
[cols="h,4*",options="header",width="50%"]
|==================================
|      |West |Central |East | Total
|Q1    |270  |292     |342  | 904
|Q2    |322  |276     |383  | 981
|Q3    |298  |252     |274  | 824
|Q4    |344  |247     |402  | 993
|==================================

Output markup AsciiDoc source

Table 9. AsciiDoc style in first column, Literal in second
Output markup	AsciiDoc source
Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. `Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.` Code filter example `''' A multi-line comment.''' def sub_word(mo): ''' Single line comment.''' word = mo.group('word') if word in keywords[language]: return quote + word + quote else: return word` Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Fusce euismod commodo velit. Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis. Nulla porttitor vulputate libero. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus.	Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. ----------------------------------- Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. ----------------------------------- .Code filter example [source,python] ----------------------------------- ''' A multi-line comment.''' def sub_word(mo): ''' Single line comment.''' word = mo.group('word') if word in keywords[language]: return quote + word + quote else: return word ----------------------------------- - Lorem ipsum dolor sit amet, consectetuer adipiscing elit. * Fusce euismod commodo velit. * Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. * Vivamus fringilla mi eu lacus. * Donec eget arcu bibendum nunc consequat lobortis. - Nulla porttitor vulputate libero. . Fusce euismod commodo velit. . Vivamus fringilla mi eu lacus.

Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Code filter example

''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- Fusce euismod commodo velit.
- Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel.
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.
Nulla porttitor vulputate libero.
1. Fusce euismod commodo velit.
2. Vivamus fringilla mi eu lacus.

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

-----------------------------------
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
-----------------------------------

.Code filter example
[source,python]
-----------------------------------
''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word
-----------------------------------

- Lorem ipsum dolor sit amet,
  consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  * Qui in magna commodo, est labitur
    dolorum an. Est ne magna primis
    adolescens. Sit munere ponderum
    dignissim et. Minim luptatum et vel.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc
    consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.

AsciiDoc source

[cols="asciidoc,literal",options="header",grid="cols"]
|==================================
|Output markup |AsciiDoc source
2*|
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

-----------------------------------
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
-----------------------------------

.Code filter example
[source,python]
-----------------------------------
''' A multi-line
    comment.'''
def sub_word(mo):
   ''' Single line comment.'''
    word = mo.group('word')
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word
-----------------------------------

- Lorem ipsum dolor sit amet,
  consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  * Qui in magna commodo, est labitur
    dolorum an. Est ne magna primis
    adolescens. Sit munere ponderum
    dignissim et. Minim luptatum et vel.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc
    consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.

|==================================

Table 10. Cell containing lots of example markup elements
URLs: The AsciiDoc home page, https://asciidoc.org/, email Joe Bloggs, joe.bloggs@example.com, joe.bloggs. Link: See AsciiDoc source. Emphasized text, Strong text, `Monospaced text`, “Quoted text”. Subscripts and superscripts: e^πi+1 = 0. H₂O and x¹⁰. Some ^{super text} and _{some sub text} Replacements: © copyright, ™ trademark, ® registered trademark, — em dash, … ellipsis, → right arrow, ← left arrow, ⇒ right double arrow, ⇐ left double arrow.

AsciiDoc source

|====================================================================
|'URLs':
https://asciidoc.org/[The AsciiDoc home page],
https://asciidoc.org/,
mailto:joe.bloggs@example.com[email Joe Bloggs],
joe.bloggs@example.com,
callto:joe.bloggs[].

'Link': See <<X1,AsciiDoc source>>.

'Emphasized text', *Strong text*, +Monospaced text+, ``Quoted text''.

'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^.
Some ^super text^ and ~some sub text~

'Replacements': (C) copyright, (TM) trademark, (R) registered trademark,
-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
double arrow, <= left double arrow.
|====================================================================

Table 11. Nested table

Normal cell

Cell with nested table

Nested table cell 1

Nested table cell 2

AsciiDoc source

[width="75%",cols="1,2a"]
|==============================================
|Normal cell

|Cell with nested table

[cols="2,1"]
!==============================================
!Nested table cell 1 !Nested table cell 2
!==============================================

|==============================================

Table 12. Spans, alignments and styles
1	2	3	4
5	`6`		`7`
8
9	`10`

AsciiDoc source

.Spans, alignments and styles
[cols="e,m,^,>s",width="25%"]
|================
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|================

Table 13. Three panes
Top Left Pane Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.	Right Pane Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. `Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui.` Code filter example `''' A multi-line comment.''' def sub_word(mo): ''' Single line comment.''' word = mo.group('word') if word in keywords[language]: return quote + word + quote else: return word` Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Fusce euismod commodo velit. Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis. Nulla porttitor vulputate libero. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus.
Bottom Left Pane Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. Consul necessitatibus per id, consetetur, eu pro everti postulant homero verear ea mea, qui. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Fusce euismod commodo velit. Qui in magna commodo, est labitur dolorum an. Est ne magna primis adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. Vivamus fringilla mi eu lacus. Donec eget arcu bibendum nunc consequat lobortis. Nulla porttitor vulputate libero. Fusce euismod commodo velit. Vivamus fringilla mi eu lacus.

AsciiDoc source

.Three panes
[cols="a,2a"]
|==================================
|
[float]
Top Left Pane
~~~~~~~~~~~~~
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

.2+|
[float]
Right Pane
~~~~~~~~~~
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

-----------------------------------
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
-----------------------------------

.Code filter example
[source,python]
-----------------------------------
''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word
-----------------------------------

- Lorem ipsum dolor sit amet,
  consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  * Qui in magna commodo, est labitur
    dolorum an. Est ne magna primis
    adolescens. Sit munere ponderum
    dignissim et. Minim luptatum et vel.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc
    consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.

|
[float]
Bottom Left Pane
~~~~~~~~~~~~~~~~
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.

- Lorem ipsum dolor sit amet,
  consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  * Qui in magna commodo, est labitur
    dolorum an. Est ne magna primis
    adolescens. Sit munere ponderum
    dignissim et. Minim luptatum et vel.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc
    consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.

|==================================

Combinations of align, frame, grid, valign and halign attributes

	frame	grid	valign	halign
	all	all	top	left

AsciiDoc source

:frame: all
:grid: all
:halign: left
:valign: top

[options="header"]
|====
||frame | grid |valign |halign
v|&nbsp;
&nbsp;
&nbsp;
|{frame} | {grid} |{valign} |{halign}
|====

Table 14. Table test
	frame	grid	valign	halign
	sides	rows	middle	center

AsciiDoc source

:frame: sides
:grid: rows
:halign: center
:valign: middle

.Table test
[width="50%",options="header"]
|====
||frame | grid |valign |halign
v|&nbsp;
&nbsp;
&nbsp;
|{frame} | {grid} |{valign} |{halign}
|====

	frame	grid	valign	halign
	topbot	cols	bottom	right

AsciiDoc source

:frame: topbot
:grid: cols
:halign: right
:valign: bottom

[align="right",width="50%",options="header"]
|====
||frame | grid |valign |halign
v|&nbsp;
&nbsp;
&nbsp;
|{frame} | {grid} |{valign} |{halign}
|====

	frame	grid	valign	halign
	none	none	top	left

AsciiDoc source

:frame: none
:grid: none
:halign: left
:valign: top

[align="center",width="50%",options="header"]
|====
||frame | grid |valign |halign
v|&nbsp;
&nbsp;
&nbsp;
|{frame} | {grid} |{valign} |{halign}
|====