Tables in pure Markdown


Markdown without tables is a complete non-starter for my needs; using Markdown as a sort of HTML table macro is one of its primary benefits (especially since right-aligning a numeric table column is much more work than it should be in HTML). I doubt I’m alone, or even the minority.

The simple pipe syntax is obviously the least surprising approach (though fenced TSV or CSV or JSON arrays of arrays would be very useful to display as tables), even though it may have some inconveniences. It’s intuitive, and it has precedence.

I think the “settle the core first” argument is a false choice, a purely artificial bottleneck. There ought to be enough participation to work on more than a single thing at a time.


Considering it has been literally a DECADE since the last “spec” release for Markdown, I am not sure I agree.


It is better to have the core spec set in stone and then have standard extension to it. The work on both can be in parallel.


Fair enough, but I guess I’m more optimistic about the CommonMark effort. It organizes and provides momentum that wasn’t really there before (was almost disparaged in many ways, by the only available authority then).


I just want to throw weight behind the case for one - any - of the justified tables to be in the spec as soon as possible, not just html insertion.

I’m visiting here as a commercial user of MD and no real sort of developer. I believe ours is a typical use case for Markdown; we don’t use it just to make creating html easier, we use it because 50% of our users will look at resulting html and 50% will read the .md or .txt in its raw form, in a monospace font in something like NP++ We love Markdown because we can make both equally legible.

A largish table is tricky to produce using pipe-dash or similar, but worth it’s weight in gold over trying to read a html table in the .md


If there is a pressing need to add tables, I suggest that your developers adopt a popular flavour in the meantime (GitHub’s table syntax for example). It might be a while before the CommonMark table extension syntax is decided upon; the focus right now is to solidify the core. I’m sure that someone will write a conversion script if CommonMark goes with different syntax (or you could just use GitHub Flavored Markdown for legacy documents).


I believe markdown-it has a tables extension, but interprets "core"
syntax in conformity to commonmark. So it might be a good solution
for you while the spec is being developed.


Tables looks good in “markdown-it” demo:

Seems like pipes and dash will be the way to go, once core is settled.


I don’t see why multiple table syntaxes couldn’t be supported (the same way Markdown has multiple lists, headers, and links). GitHub-style tables are common, but Pandoc includes some minimalist tables which might be preferable if the writer wishes to avoid page clutter. E.g.

 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between

It would be preferable to use CSS or some automated mechanism for aligning the columns though. HTML does not encourage the writer to include presentational information for a reason; I don’t think CommonMark should either.


markdown-it has no multililne tables support only because CM spec not exists. We selected GH as the most common and which will not became broken after spec available.


Just wanted to support the few contributors of this thread who mentioned colspan and rowspan. They are critical for technical reports and academic paper writing.


May be core markdown is not the best place for such ideas, but here’s one to simplify creating and editing tables with long lines in cells.

| Header      | Another header     |
| short line  | very long line }_  |
| additiona}_ | they even may b }_ |
{ very long line can be continued right under the table }
{ additional lines are listed in order they appear in table (rtl, ttb) }
{ they even may be multilined
as this line }
  1. It’s readable: actual table contains enough text to get an idea of its full content, but not too much to bloat
  2. It’s editable: only “}_” is mandatory, rest of the text is just for readability; thus to change the full text, no cell editing is required. Adding new long line also doesn’t require any reordering.


Since Markdown uses soft breaks, you could just break the sentence up over multiple lines. The parser would then render the lines together as a single sentence/line.

It might be best to require explicit divider lines between cells in case the cell contains multiple paragraphs. In any case, I think it’s worth making the formatting rules within a cell the same as the formatting rules for content outside of a cell.


The downside to this is that it isn’t applicable to “pipe” tables, and changes to “simple” tables frequently cause “respacing” and “rebreaking”.


I’m not sure how pipe tables behave now in the various implementations, but is there any reason why they couldn’t be designed this way in CommonMark?


If all you need is some text or data presented in a table-like way, you need no extension, you could just use a pre block and tabulate to taste:

A header            Another header             Price
Some text here      Another bit of text        34,10
Lorem ipsum         In principo creavit       624,45
                                    Total:    658,55

The result is primitive but flexible as you can be very creative with your formatting.

If you need to output an HTML table, then you need a specific syntax.
I really like the Pandoc simple+multiline tables. They have the same benefits as Github flavored ones and are very legible, easier to write, visually light, intuitive (no special char to remember)…

If we don’t need alignment (some argued it should be left to CSS) we could imagine an even simpler syntax for basic tables:

# Header       Header 2
| First field  Second field

A header (# or another character) followed by a pipe on the next line would be a table header line. 2 or more spaces mean a new column.

RFC Spec extension for *tables*: Syntax and transformation rules

I think your pre block and tabulate is quite nice. I would still request that tables require/support pipes, as it is not always a given that alignment is respected in all text viewers/editors (e.g. one that strips out all whitespaces

A header           | Another header      |   Price
Some text here     | Another bit of text |    34,10
Lorem ipsum        | In principo creavit |    624,45
||                                   Total:   658,55

The difference between the standard pipe and dash, and the similarities to yours is that it allows for lazy horizontal rules to separate cells. But it doesn’t omit the row cell separator to ensure that the division is more clearer for the reader and parser.

(e.g. Easy for the parser to tell that the “Total: 658,55” should be in the third cell.)

If there is a need to distinguish headers in tables. This could be an option, of specifying thicker lines.

A header           | Another header      |   Price
Some text here     | Another bit of text |    34,10
Lorem ipsum        | In principo creavit |    624,45
||                                   Total:   658,55


One request I would make when implementing a spec for tables - don’t make a header required. For example, in kramdown, you can simply use

| Item 1  | Item 2 |
| Item 3  | Item 4 |

and it will produce a table without a header. I’ve used this style in many instances where I just need some information columnized but don’t want a header row. If a line of dashes are needed to start the table, that’s fine. But let’s not require a table head (most other implementations do require it, unfortunately).

RFC Spec extension for *tables*: Syntax and transformation rules

Instead of discussing additional or less used table formats we should first specify pipe tables:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

Pipe before first and after last column are optional unless the table has only one column:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

Spaces before and after pipes optional:

First Header|Second Header
--------------|   --------------
Content Cell |    Content Cell

But this is not allowed, neither can header be omitted:

First Header  | Second Header
Content Cell  | Content Cell

Colons can be used to indicate column alignment:

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -------------:|
| col 3 is      | some wordy text | $1600         |
| col 2 is      | centered        | $12           |
| zebra stripes | are neat        | $1            |

Columns need not be vertically aligned:

fruit| price

That’s all. The hard work is putting this rules into a clear and strict specification.

RFC Spec extension for *tables*: Syntax and transformation rules
RFC Spec extension for *tables*: Syntax and transformation rules

FYI this form is supported by “pandoc” and “Maruku 0.7.2”

 field1 | field2
 entry0 | entry1
 entry2 | entry3
 entry4 | entry5

I like this form (in addition to the standard github flavored pipe tables) , since it easier to edit tables without having to worry about exact alignment of the space|+field2 +---------------- +entry0+|+entry1 +entry2+|+entry3 +entry4+|+entry5