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:

1	2	A
3	4	B
5	6	C

Table 1. Simple table

AsciiDoc source

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

Column 1	Column 2
6	Three items
1	Item 1
2	Item 2
3	Item 3

Table 2. Table with title, header and footer

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
|======================

	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

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

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
|==========================

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

Table 4. A table with externally sourced CSV data

AsciiDoc source

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

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 5. DVS formatted table

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
|====================================

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

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).

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

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.

Default paragraphs

Centered verses

Per id.

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.

Table 7. Default and verse styles

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.
|===================================

	West	Central	East	Total
Q1	270	292	342	904
Q2	322	276	383	981
Q3	298	252	274	824
Q4	344	247	402	993

Table 8. Horizontal and vertial headings

AsciiDoc source

.Horizontal and vertial 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

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.

Table 9. AsciiDoc style in first column, Literal in second

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.

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

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.

Table 10. Cell containing lots of example markup elements

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.
|====================================================================

Normal cell

Cell with nested table

Nested table cell 1

Nested table cell 2

Table 11. Nested table

AsciiDoc source

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

|Cell with nested table

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

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

1	2	3	4
5	`6`		`7`
8
9	`10`

Table 12. Spans, alignments and styles

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
|================

Top Left Pane

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.
1. Fusce euismod commodo velit.
2. Vivamus fringilla mi eu lacus.

Bottom Left Pane

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.
1. Fusce euismod commodo velit.
2. Vivamus fringilla mi eu lacus.

Table 13. Three panes

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}
|====

	frame	grid	valign	halign
	sides	rows	middle	center

Table 14. Table test

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}
|====

Last updated 2002-11-25 00:37:42 UTC