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

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. 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':
    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}
    |====