»Home
»User Guide
»Installation
»FAQ
»asciidoc(1)
»a2x(1)
»API
»Plugins
»Cheatsheet
»Tests
»ChangeLog
»Support
AsciiDoc
Text based document generation

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

    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, http://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. H2O and x10. 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':
http://asciidoc.org/[The AsciiDoc home page],
http://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.

    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.

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.

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