Tables in pure Markdown


#143

#144

This discussion will soon be four years old, it would be lovely if at some point something was standardized :slight_smile:


#145

A pipe table syntax with lots of features:

|              | Header 1        | Header 2                       || Header 3                       ||
|              | Subheader 1     | Subheader 2.1  | Subheader 2.2  | Subheader 3.1  | Subheader 3.2  |
|==============|-----------------|----------------|----------------|----------------|----------------|
| Row Header 1 | 3row, 3col span                                 ||| Colspan only                   ||
| Row Header 2 |       ^                                         ||| Rowspan only   | Cell           |
| Row Header 3 |       ^                                         |||       ^        | Cell           |
| Row Header 4 |  Row            |  Each cell     |:   Centered   :| Right-aligned :|: Left-aligned  |
:              :  with multiple  :  has room for  :   multi-line   :    multi-line  :  multi-line    :
:              :  lines.         :  more text.    :      text.     :         text.  :  text.         :
|--------------|-----------------|----------------|----------------|----------------|----------------|
[Caption Text]

  1. Multiple rows of headers and subheaders (Thank you vas)

  2. Row headers, which are indicated by replacing dashes - with equals signs = in the first column’s delimiter row (Thank you again vas)

  3. Row spans using a carat/circumflex ^ (Thank you jgm)

  4. Column spans using multiple pipes ||| (MultiMarkdown, Maruku)

  5. Caption surrounded by brackets [ ] on the line just below the table (MultiMarkdown)

  6. Multi-line cell continuation using a colon : in place of a pipe | (like in PostreSQL’s interactive terminal, as discussed by David Wheeler in RFC: A Simple Markdown Table Format and suggested above by illionas)

  7. Per-cell alignment using colon(s) : inside a cell, to the left/right/both of the cell’s first line of text (inspired by the |:---:| syntax for per-column alignment)


An alternative syntax, for better compatibility with existing pipe tables:

| Caption Text |                 |                |                |                |                |
|--------------|-----------------|----------------|----------------|----------------|----------------|
|              | Header 1        | Header 2       |        <       | Header 3       |        <       |
|              | Subheader 1     | Subheader 2.1  | Subheader 2.2  | Subheader 3.1  | Subheader 3.2  |
|==============|-----------------|----------------|----------------|----------------|----------------|
| Row Header 1 | 3row, 3col span |       <        |        <       | Colspan only   |        <       |
| Row Header 2 |       ^         |       <        |        <       | Rowspan only   | Cell           |
| Row Header 3 |       ^         |       <        |        <       |       ^        | Cell           |
| Row Header 4 |  Row            |  Each cell     |:   Centered   :| Right-aligned :|: Left-aligned  |
|.            .|. with multiple .|. has room for .|.  multi-line  .|.   multi-line .|. multi-line   .|
|.            .|. lines.        .|. more text.   .|.     text.    .|.        text. .|. text.        .|

A future extension could implement this syntax.

For now, in GFM and other existing Markdown flavors, it falls back to an ordinary table whose cells contain symbols that visually represent the additional features:

  1. One row in the rendered table consists of cells containing only dashes - and cells containing only equals signs =. This resembles a “delimiter row”. Cells above this row represent headers and subheaders. Cells below that row represent other table cells.

  2. In the “delimiter row”, if the first cell contains only equals signs =, it indicates that the cells in the first column represent row headers.

  3. A row span is represented by cells containing only a carat/circumflex ^.

  4. A column span is represented by cells containing only a “less-than” symbol <. (Inspired in part by 0x666C697473’s above proposal to use a “greater-than” symbol > for column spans.)

  5. A caption is represented by text in the top-left cell (above all other cells, headers, etc.)

  6. Multi-line cell continuation is represented by row(s) whose cells each start and end with a single dot that is whitespace-separated from the cell’s text content. |. (text) .| Visually, the dots in each column resemble a vertical ellipsis which indicates that the above cell continues downward.

  7. Per-cell text alignment is indicated if a cell (or, in a multiline cell, the first line) starts and/or ends with a colon that is whitespace-separated from the cell’s text content. | (text) :|, |: (text) |, |: (text) :|

In this table, the Markdown text can be compressed to remove extra dashes, equals signs, and whitespace, as long as there remains whitespace next to colons |: :| for alignment and next to dots |. .| for cell continuation.

EDIT: I have revised the above syntax proposal to simplify it. The earlier version was as follows:

|==============|                 |                |                |                |                |
|--------------|-----------------|----------------|----------------|----------------|----------------|
|              | Header 1        | Header 2       |        <       | Header 3       |        <       |
|              | Subheader 1     | Subheader 2.1  | Subheader 2.2  | Subheader 3.1  | Subheader 3.2  |
|==============|=================|================|================|================|================|
| Row Header 1 | 3row, 3col span |       <        |        <       | Colspan only   |        <       |
| Row Header 2 |       ^         |       <        |        <       | Rowspan only   | Cell           |
| Row Header 3 |       ^         |       <        |        <       |       ^        | Cell           |
| Row Header 4 |  Row            |  Each cell     |:   Centered   :| Right-aligned :|: Left-aligned  |
|.            .|. with multiple .|. has room for .|.  multi-line  .|.   multi-line .|. multi-line   .|
|.            .|. lines.        .|. more text.   .|.     text.    .|.        text. .|. text.        .|
|--------------|-----------------|----------------|----------------|----------------|----------------|
| Caption Text |

#146

There is a related topic discussing the introduction of figure environments and captions for images: Image tag should expand to figure when used with title It would be nice if a unified caption syntax would emerge from these two topics.


#147

Captions could be added as a table row at the bottom (or perhaps top) of a pipe table. But since an image isn’t made up of rows it wouldn’t make sense for image captions to also use this syntax. However, both transcluded images and CSV table content blocks do share the same caption syntax.