Tables in pure Markdown


I’d be inclined to give a lot of weight to this disadvantage, given the fundamental focus of Markdown on source readability. (Easy-to-read wins over easy-to-write with Markdown; not all lightweight markup formats make that same choice, but it is what distinguishes Markdown.)


Just landing on this website. I read that 2 years ago, the table spec was relegated as not considered part of the ‘core features’. After two years, I don’t see a clear intention of incorporating tables into the core.

This is quiet disappointing, as there are major players supporting tables for years (i.e. github). I would rather be inclined to use one of those major players as the standard, like GFM.

Is there any serious and clear roadmap for tables?


There’s a clear intention to add tables, yes. But it has proved difficult enough to get all the details ironed out for the core elements, and that should happen first. Also, as you can see above, there are a lot of tricky issues to resolve in deciding on an appropriate table syntax. In the mean time, nothing stops you from using an implementation that supports CommonMark + a non-official table extension. (And there are many implementations that offer this, e.g. markdown-it.)


While the time passes, some de-facto standards emerge. Any attempt to reinvent the wheel will cause a bigger conflict. I think it is time for you guys to take the common denominator of the major players and write down a basic proposal for tables. I guess that would be pipes and hyphens.


Welcome to the site!

I think the main reason tables are included in extensions, rather than in the CommonMark core, is that the original Markdown syntax by John Gruber did not include tables at all. Many other flavors and implementations of Markdown don’t include tables either, not even basic ones with pipes and hyphens.

There’s something to that. I suggested something similar as a mostly-least-common-denominator approach. On the other hand, I would worry about trying to impose any sort of table standard where none exists.

CommonMark isn’t quite a “standards committee,” it’s really just yet another Markdown flavor, but even so I feel our main goal is to specify rather than to innovate. Given the huge variety of table syntaxes and potential conflicts, it might better to step back and let the major players fight it out as the de-facto-standardization process runs its course.


I indeed like the idea of leaning towards the wikisyntax. One property it has is that it’s relatively easy to write without the help of any sophisticated editor (once you know the syntax, which looks rather difficult).

Optionally put new cell on new line (with leading space)

My point would be to mix in the possibility of writing a new cell on a new line into pipe tables, like this:

  • ^[|].* indicates new row (starts with pipe)
  • ^\s+[|].* indicates new cell (starts with spaces then pipe)

Or rather:

  • replace(/\n^\s+[|]/gm, "|") – remove newline/linefeed from lines starting with spaces before the pipe (inside identified tables). See my example at
  • then evaluate table as usually → This means there would be no big changes to pipe tables, i guess.
  • Also works with tables that lack leading or trailing pipes, since the replace rule would only match inside the rows.
| A1
 | B1
 | C1
 | D1 
| A2
 | B2
 | C2
 | D2

Until here everything about my proposal would be ***optional!***. No need to use it for small tables that are compact enough to fit into the editors view anyway. The point is that stuffed cells would get more overview.

| A1 | B1    | C1 | D1 |
| A2 | B2
    | C2: Lorem ipsum dolor sit amet, qui repudiare dissentias mediocritatem ut, quod consequat ex qui, ius in quaerendum repudiandae. Eu soleat repudiandae quo, est ullamcorper definitiones ut, cu augue sententiae quo. Ea casem nihil scaevola has, eu consul propriae pro. Nec feugait corrumpit te, est ut mollis bonorum.
    | D2 |

You could also space out the table so that it would be easy to grasp which cell is in which collum, even if the cells have content of different length.

| A1 Lorem ipsum dolor sit amet, qui repudiare 
    | B1 dissentias mediocritatem ut, quod consequat ex qui, ius in quaerendum repudiandae. 
        | C1 Eu soleat repudiandae cu augue sententiae
            | D1 Ea casem nihil scaevola has, 
| A2 repudiare dissentias mediocritatem ut, quod 
    | B2 repudiandae quo, est ullamcorper
        | C2 est ut mollis bonorum.
            | D2 Nec feugait corrumpit 

Block level elements

However, if we would change the syntax a bit it might enable us to use block level elements inside tables!, which would be really awsome!

| A1 | B1    | C1 | D1 |
| A2 | B2
    | - C2 ex qui
      - Lorem ipsum
      - dolor sit amet,
      - qui repudiare
    | D2 |

compressed tables

I think this could be nicely combined with the idea of compressed pipe tables mentioned by @mofosyne with - or = to mark <TH>.

|= A1
 |= B1
 |= C1
 |= D1                        
|  A2
 |  B2
 |  C2
 |  D2

I personally prefer the = visually. Plus, maybe the combination |-could be used to more clearly start a new row, then you could even write a table in one single line like this: |= A1 | B1 |- A2 | B2. (But this would also require more changes to the syntax than just removing newlines.)

The |= might also be used to mark a <TH> anywhere in the table. Most common usecase might be flipped tables, where the headers are on the left, instead of on top (i.e. A1 and A2 would be headers in the examples above).

Align could be incorporated into the header marker like this: |:= left align, |:=: center align, |=: right align, or like @mofosyne proposed e.g. |:= header =: for center align.


For rowspan I would suggest the “obvious” symbol for continuation, i.e. the three dots that form the “ellipsis” .... E.g. in the following example C2 and C3 would be merged into one cell that spans two rows.

|  A1  |  B1 |  C1  |  D1  |
|  A2       ||  C2  |  D2  |
|  A3  |  B3 |  ... |  D3  |


I just noticed that my rowspan suggestion with ellipsis would take relatively long to be noticed by the parser (when it gets to cell C3) and only then can modify the rowspan attribute of the element C2. I don’t know whether this would slow it down a lot, but i thought that alternatively we’d just need to find a symbol for rowspan which we simply place in the same position as the repeated bars:

Visually i’d propose the exclamation mark (!), because of it’s vertical nature and the arrow-like downwards pointing of the point below it. It’s also relatively symetric to the double bar syntax, (repeat the ! if bigger rowspan is needed). Just like in HTML, the cell below would simple be omitted. Only disavantage I see, is that it’s relatively difficult to spot the difference between the bar and the exclamation mark. (The full-stop would probably be used to often as the last symbol and therefore generate unwanted behavior of the table. I doubt however, that there’s much shouting in tables.)

|  A1  |  B1 |  C1  |  D1  |
|  A2       ||  C2 !|  D2  |
|  A3  |  B3        |  D3  |


A slightly extended markdown table syntax proposed by David Wheeler from 2009 contains the proposal for “continued content”. He proposes the colon (:) to replace the pipe (|) in lines that continue cells from the preceeding line. I would propose the apostrophe (') instead, but that’s merely a matter of taste.

|   |   |   |
| a | b | c |
: a : b : c :
|   |   |   |

variant with '

|   |   |   |
| a | b | c |
' a ' b ' c '
|   |   |   |

The big advantage of this syntax is that it allows block-level-elements.

However, the drawback may be that (just like gridtables) it disrupts the text into several parts, seperated by random other elements, e.g. if you search the text for “a a” you wouldn’t find it, because the raw text reads “a b c a”. This could be a problem for git/diff or the like.

In comparison, the syntax i proposed above (with space + bar in a new line) is more git/diff-friendly, but doesn’t retain the form of a table as much.


If you take the ideas from the transclusion/inclusion discussion you could also extend table cells with simple references:

| Theme       | List                 |
| Shopping    | :[grocery list][B2]  |
| Programming | :[HTML elements][B3] |

- oranges
- bananas
- apples
- lemons

<!-- some code block -->


Please implement mediawiki tables:

It’s much easier to read and edit big tables, unlike current markdown implementation.
I think we no need to do any changes to this format, just take and implement it, because:

  • it will have common standard with mediawiki tables, so you can just copy&paste tables between this formats.
  • it is simple to implement, because already written
  • Users already know this format and successful work with it



Why would MediaWiki tables be better than just HTML?


! style="text-align:left;"| Item
! Amount
! Cost


  <th style="text-align:left;">Item

GitHub-Flavored Markdown

|  Item  | Amount |  Cost |
| Orange |     10 |  7.00 |
| Bread  |      4 |  3.00 |
| Butter |      1 |  5.00 |
| Total  |        | 15.00 |

Note: there is no way to make the Total on the bottom act as a header in GFM.


BTW, apparently has HTML tables disabled. There’s a checkbox to enable HTML tables. GFM tables require a plugin. MediaWiki tables don’t exist for Discourse, AFAIK.

Just mentioning it, because an earlier draft of the above post used a table to compare GFM, MediaWiki, and HTML tables.


Having a common standard with mediawiki is not a good benchmark in my book for adding anything to markdown. I’m not impressed by the format in the least given its tendency toward verbosity and awkward editing syntax.

Not for a markdown parser it’s not. I’m not sure if you’ve ever written a parser, but I can tell you that you can’t just copy and paste code between different parsers and expect anything to work. Also, ease of implementation should not be considered for adding features to markdown. Ease and success of use is what should be considered if the format is to be successful.

I consider this to be somewhere between the bandwagon and genetic fallacies. Also, you’re probably speaking from the position of someone who’s familiar with media wiki. There are many people who are not familiar with media wiki who would not be successful working with it.

To me I think implementing mediawiki tables is a bad idea. It’s a bad idea for several reasons:

  • they’re verbose
  • they’re fragile
  • they fail the readability test


I think they’re verbose because they add a bunch of extra nonsense characters to what you need to type that aren’t particularly an improvement over raw HTML


I think they’re fragile because, in my experience, changing only a few characters, or accidentally adding spaces in a few places cause the entire table to render awkwardly without an easy way of determining where the issue is.


One of the core concepts of markdown is that reading the source as raw text maps fluidly to what gets rendered on the page. Essentially it’s the syntax that’s been in use in emails since the 90’s when all we had was monospaced fonts for formatting. Attempting to grok a mediawiki table is…painful. Compare the source to a GFM table and it obvious which one better represents a table in a text file.

With all of that said: convince me that I’m wrong. If you really want mediawiki tables, implement them as a markdown extension and prove that they’re the best way to handle tables. If you can show the world just how much better they are than the other alternatives with a compelling implementation and use cases, you’ll have enough popular support to add them directly to the spec.

Personally, I prefer GFM tables, but my ideal would be the ability to add <table src="data.csv"></table> directly to HTML as part of that spec.


Why not just a boring old list to html table converter? This conversation has been going on for a very long time I see -__-

I think all implementations of tables should be extensions. Cause everyone seems to want to do it differently.

There can be a “default extension”, (something enabled by default) and if the user doesn’t like it, it should be made easy, and clear how they should be able to change the default implementation.

Tables might be one of the more divisive parts of CommonMark. It would be good if there was some way to change reformat the tables afterward. A standard implementation to convert between table formats.


Well, according to BabelMark, pipe tables are implemented by:

  • pandoc 1.19.2
  • RDiscount 2.1.7
  • MD4C 0.2.2
  • PHP Markdown Extra 1.2.8
  • s9e\TextFormatter (Fatdown/PHP)
  • kramdown 1.2.0
  • cebe/markdown GFM 1.1.1
  • cebe/markdown MarkdownExtra 1.1.1
  • showdown (flavor: github) 1.6.4
  • Maruku 0.7.3.beta1
  • Maruku (Math-Enabled) 0.7.3.beta1
  • Blackfriday
  • Earmark 1.1.1

These ones also support pipe tables, but Babelmark doesn’t turn it on:

Out of the ones that don’t implement pipe tables, these ones have no support for tables at all:

  • commonmark 0.27.0
  • 1.0.1
  • cheapskate
  • pandoc (strict) 1.19.2 (It works in non-strict mode, see above)
  • 1.0.2b8
  • lunamark 0.4.0
  • PHP Markdown 1.0.2 (It works in Extra mode, see above)
  • MD4C (strict) 0.2.2 (It works in non-strict mode, see above)

These ones support tables, but not pipe tables:

  • Gambas 3.8.90


Basically. pipe tables are the most common? The reason pipe tables aren’t implemented in some is because they are following commonmark spec?

How difficult would you say implementing pipe tables would be?


Some of them don’t want to implement anything outside of, which doesn’t support tables. Others don’t want to support anything outside of CommonMark, yes.

This hard


Around 180 lines of code, excluding tests. Plus its already written. plus it isn’t dependent on regex.

Stylistically. I am for pipe tables.

mediawiki is really its own beast.

Let us also not forget that pipe tables are human-readable in plain text form already, which I think is almost the most important part.

It’s not easy to maintain. (except if someone can prove me wrong.) but its very readable.

Another thing we’d have to decide on is whether to be strict about the markdown or not.



  1. For the same reason why **text** better than <b>text</b>
  2. Too many <td></td>, <tr></tr> it is unusable, I want to get it easy in markdown.

@zzzzBov, your answers about:

Here you right, we can create self implemintation, but I think that mediawiki markup syntax can serve as a good practices for to do this.
Nevertheless, the main reason was:

Ok, go next:

This is wrong, I am worked with markdown too much. But just now I forced to use mediawiki markup for one project.
I was surprised at how it laconic and simple for creating tables, unlike markdown.
Using markdown I try in every possible way to avoid the use of tables.
Here are the main reasons, I will describe why it so below.

OK, but what about this |:-------|-------:|------:| ?

I think it is main problem of curent markdown tables implementation.

For example this table:

What if I needed to add some new Item with long name? We have two cases here:

  1. It will be broken:
@@ -2,5 +2,6 @@
 | Orange |     10 |  7.00 |
 | Bread  |      4 |  3.00 |
+| Super Snickers |       1 |   1.00 |
 | Butter |      1 |  5.00 |
-| Total  |        | 15.00 |
+| Total  |        | 16.00 |
  1. Or we need to reformat ALL the table:
@@ -1,6 +1,7 @@
-|  Item  | Amount |  Cost |
-| Orange |     10 |  7.00 |
-| Bread  |      4 |  3.00 |
-| Butter |      1 |  5.00 |
-| Total  |        | 15.00 |
+|  Item          | Amount |  Cost |
+| Orange         |     10 |  7.00 |
+| Bread          |      4 |  3.00 |
+| Super Snickers |      1 |  1.00 |
+| Butter         |      1 |  5.00 |
+| Total          |        | 16.00 |

Yes, you can try to use pre allocated space for changes. But it’s never possible to know for sure how many space you will needed. And sooner or later it will break.
Add here the text formatting inside the cells and get the real hell on the wheels.

Yes, this is acceptable for small tables, but what if you need to make a big one?

Here is markdown example:

| Server | IP | Description |
| cl1 | | This is my first server in the list |
| cl2 | | This is another one server |
| windows-5BSD567DSLOS | | This is customer windows vm. dont touch this!  |

Same but in mediawiki syntax:

| Server
| IP
| Description
| cl1
| This is my first server in the list
| cl2
| This is another one server
| windows-5BSD567DSLOS
| This is customer windows vm. dont touch this!
| Some printer

And this table may be very long.

Which format is more readable here?

In addition it more applicable for tracking changes in git:

@@ -12,7 +12,7 @@
 | This is another one server
 | windows-5BSD567DSLOS
 | This is customer windows vm. dont touch this!

unlike markdown:

@@ -2,6 +2,6 @@
 | cl1 | | This is my first server in the list |
 | cl2 | | This is another one server |
-| windows-5BSD567DSLOS | | This is customer windows vm. dont touch this!  |
+| windows-5BSD567DSLOS | | This is customer windows vm. dont touch this!  |

This is wrong, because same problem may be acceptable for markdown and html tables.
You can be confused, and make mistakes anywhere.

Thanks a lot! I hope I convinced you… :slight_smile:


I think we can simple solve this if just allow set “newline” before “|” symbol.

So it will look like this in markdown:

| Server
| IP
| Description
| cl1 
| This is my first server in the list
| cl2 
| This is another one server
| windows-5BSD567DSLOS
| This is customer windows vm. dont touch this! 
| Some printer

Or the first table:

| Item
| Amount
| Cost
| Orange
| 10
| 7.00
| Bread 
| 4
| 3.00
| Butter
| 1
| 5.00
| Total 
| 15.00