Tables in pure Markdown

Just to offer a very slightly different perspective … although a nicely formatted “markdown table” is really nice to look at and read, it’s not nice to author and maintain. Imagine a long table, where every row had cell contents of different lengths … it either looks like an unaligned mess that’s impossible to parse visually, or it’s a nightmare to go through and update every row’s whitespace count so the pipes line up when viewed after some new content has been added or updated.

IMO, markdown should be easy to author first, easy to read without first converting to HTML second.

That being said, I don’t disagree that it shouldn’t be a part of the spec … just offering a different perspective :slight_smile:


That’s true, I definitely agree that it’s a drawback and can prove to be annoying at times to author and maintain tables in this fashion. If there’s a better, more intuitive solution, I’m all for it, so long as it doesn’t look like <table>...</table> :wink:

1 Like

You don’t have to write all the spaces to make the table look nice. Even with the Github Extension this is optional. You can do tables like this:

| Header  | Another Header |
| field 1 | value one      |

Or like this:

| Header | Another Header |
| field 1 | value one |

Sure the first one is nicer, but it shouldn’t matter if you align the whitespaces.


oh I know it still parses correctly … but if the table is longer than that, or has more columns, it can be very difficult to parse visually (which an author would have to do in order to update and maintain the content). It gets even worse when you’re working with an editor that wraps a line (sublime, vim, et al)

1 Like

The syntax is very similar in LaTeX and even in HTML large tables are large tables. I think that’s ok to parse for humans. You just count some pipes as you would count some <td>s. This should be ok for the average joe.

1 Like

By “core markdown,” I meant simply the sorts of elements that are
supported in John Gruber’s original markdown: block quotes, lists,
etc. Tables and footnotes are not among them. I would be happy to
see markdown grow organically to have a table syntax (though I don’t
particularly like “pipe tables” – see pandoc for some nicer plain
text table formats). But it would be better to discuss that after
settling current core features.

1 Like

Note that HTML helps you out here by allowing you to omit a bunch of tags. All you really need is:

      <th>Another Header
    <td>field 1
    <td>value one

(Alternately, you can explicitly open a <tbody>, which will implicitly close the <thead>. The markup above generates a <tbody> for you when parsed, but sometimes you want an explicit element to put a class on or something, or to separate out multiple sections of body data.)

But anyway, I agree that tables should show up at some point in MD.


Please link to nicer table formats, I’m very interested.


While I agree that tables are an important use case in Markdown, I suspect that standardization will be contentious, not in whether people want them or not (that answer is clearly yes), but in the exact details of what syntax to support. For example, Pandoc currently supports at least four different syntaxes for tables:

I agree with @jgm on this one that the most important goal for this spec is to nail down the core (as in language, and let the rest happen via extensions later. It’s not like anyone’s Markdown parser is going to stop supporting tables just because it isn’t included in the spec 1.0.

1 Like

+++ rfkrocktk [Sep 04 14 00:32 ]:

Please link to nicer table formats, I’m very interested.


Since we’re talking about table syntaxes now, I’d like to throw in the MediaWiki table syntax too:

! Header !! Another header
| field 1 || something
| field 2
| something else

MediaWiki fails the “readable as plain text” sniff test by a pretty huge amount, unfortunately. It really isn’t appropriate as a MD format, imo.


For normal stuff, I don’t really see how it’s that much different. You can just as well add whitespace to align the columns etc. The only extra thing are the row separators and the leading {| and trailing |}.

Yes, those extra things are the things that don’t look like plain text. Additionally, the use of ! for headers is unusual. The syntax in the OP, used by MarkdownExtra, looks like a plain-text table you’d see people manually write in an email or the like, which is precisely the aesthetic that Markdown adheres to and what makes it attractive. Taken together, MediaWiki tables look nothing like a table; nobody unfamiliar with the syntax would understand what it was trying to do when looking at the source.

(MarkdownExtra has a special syntax for header alignment which doesn’t map to plain-text conventions, using a colon on the separator line below the header, which is weird. I’ve seen similar support for this feature by literally aligning the text; putting any whitespace on one or both sides between the header text and the pipes aligns the text accordingly. This is a better syntax, because it looks natural, does what it looks like, and acts correctly by default (centering when there’s no space or space on both sides).)


I agree, at first glance I had no idea what the MediaWiki table syntax meant. Markdown is supposed to be human and machine readable :thumbsup:

I like that MarkdownExtra gives multiple formats for tables. I like the fact that you can do either:

| Header | Header | 
| Row    | Row    |


Header | Header
Row    | Row

If it gets too much more complicated as in MarkdownExtra, I don’t think it’d be a standard feature.

However, I’m sticking to my guns in saying that yes, Markdown needs a standard table syntax.


To be honest, I see it as a failing of HTML that we can’t use a syntax such as

<table src="data.csv"></table>

to separate data from markup.

Of course, it’s possible to polyfill the behavior using

<table data-src="data.csv"></table>

and a bit of javascript.

Overall, tables would add a level of complexity that probably belongs in an extension. That way, a standards compliant markdown parser can choose not to support tables, or choose to handle tables in a different manner.


Me too, tables are an essential feature for markdown and should be in the standard.
I don’t see the need to only implement things that were in the old markdown “standard”.

The syntax of a table line as “|” and “-” seems like a good idea.

So this:

| Header | Header |
| Row    | Row    |

would be the stmd table and if you want a more fancy one you can use a table addon.

My problem with addons is that I think that many people won’t use them and if we don’t have tables in standard markdown we probably have no tables at all.


Agreed. Making certain features optional means it won’t be fully widespread. And stuff like tables and anchors are common enough to be a core standard.

A common complaint I understand about tables in markdown variants that attempts to implement this, is that it is hard to maintain. So here is some ways I think it can be simplified from “Markdown Extra” syntax for this effort.

This is [Markdown Extra Syntax for tables] (

 | Item      | Value |
 | --------- | -----:|
 | Computer  | $1600 |
 | Phone     |   $12 |

First example (Compress the pipe headers):

To indicate a field is a header you use |-, -| .
For header alignment: |:- left aligned -|, |- right aligned -:| |:- Centre aligned -:| .

|:- Header -:|:- Header -:|
|   Row      |   Row      |
|   Row      |   Row      |

Second Example ( CSV Input):

The second issue, is that people find it hard to have to deal with formatting the pipes. If alignment of cell data is of no concern to the user, then we should use CSV data as the inspiration.

I’m a big fan of CSV data, due to how easy it is to type. The ease of use comes from sticking to csv which most people use already, and combining it with a simplified table header.

If you still need alignment control for each cell, then you can just use the previous (but simplified) pipe tables shown above using |:, :|

|:- Year -|:- Make  -|:- Model                         -:| 
  1997,      Ford,      E350
  1999,      Chevy,    "Venture ""Extended Edition"""
  1999,      Chevy,    "Venture ""Extended Edition
  1996,      Jeep,      Grand Cherokee

 This is some other text, since the end of a table is implied by a new paragraph. 

example data from:

Essentially, just treat pipes as ‘optional’ for the actual cell data (which is the field that gets modified most often anyway (compared to the header). This way, we can avoid too much formatting, and heck if you are lazy, you could just remove whitespaces and it shall still be very maintainable like so:

|:- Year -|:- Make -|:- Model  -:| 
1997, Ford, E350
1999, Chevy, "Venture ""Extended Edition"" "
1999, Chevy, "Venture ""Extended Edition"" "
1996, Jeep, Grand Cherokee

The second approach is my preference. Since I believe markdown is about getting formatting out of the way of your writing.

edit: crossposted to


You could also remove the "s around cells. A new cell is started with a comma, so whitespaces should be no problem. If you want a comma you have to escape it.
As long as I get my pipe tables this sounds like a good idea. :slight_smile:
You could just copy and paste csv into markdown. That’s really handy.

|:- Year -|:- Make  -|:- Model                         -:| 
  1999,      Chevy,    Venture \, "Extended Edition"

hmmm… well, the issue with that is that it looks rather ugly. At the very least, commas like these

|:-  Year -|:- Make  -|:- Model                         -:| 
     1999,     Chevy,    "Venture, ""Extended Edition"" "

are not too ugly. I’m literally, using the ‘psudo-standard’ in csv explained by wikipedia and ratified by RFC 4180. So again, the benefit of this approach, is you can tend to copy paste most csv data (and most csv comforms to RFC4180).

RFC 4180 :

  1. If double-quotes are used to enclose fields, then a double-quote
    appearing inside a field must be escaped by preceding it with
    another double quote. For example: