Question: In the UX community, is there an agreed best practice to represent table data in textual format?

Desired outcome: If the answer is yes, then I would propose pushing for support in Commonmark.


I’m writing most of my documents in Markdown. It’s mostly great, with one of the biggest caveats being lack of native support for tables (HTML is allowed).

On the other hand, Textile has rich, native table support, based upon using the | character, like so:

|_. Col 1 |_. Col2 |
|   A1    |   B1   |
|   A2    |   B2   |

The Confluence wiki has a similar setup:

|| Col 1 || Col 2 ||
|  A1    |  B1    |
|  A2    |  B2    |

Wikipedia’s suggested markup is quite different:

{| class="wikitable"
! Col 1
! Col 2
| A1
| B1
| A2
| B2

They also allow the use of !! and || for new cells without line breaks.

Over at Commonmark (the Markdown standardisation effort), there’s a long debate on how tables should best be represented as text. To facilitate that discussion, I’m wondering if anyone has actually researched the subject, and if yes, was a conclusion reached? Is there a best practice the UX community could propose for CommonMark?

  • From a usability standpoint, something that actually looks like a table, and it relatively easy to type and remember, is good. But beyond that, I'm not sure there is anything to add to the discussion that you link to. If there were a standard, that debate probably wouldn't be happening.
    – user31143
    Jun 10, 2016 at 9:00

3 Answers 3


There is no "agreed best practice" in this, so I can't give you a definitive answer. However, I've had to deal with exactly this and had to do some user testing on a number of styles.

The style that won out was GitHub flavoured markdown, which is both easy to learn, easy to read, and easy to use. My only wish would be that saving automatically aligned the marker bars | between columns, and that the text in them would align left, right, or centred depending on the markdown written. However this is more about the implementation of the editing interface than that of the specification.

The one weak point with GitHub flavoured markdown is sub-tables. I haven't seen any decent solution for this yet, and I'm not convinced that it is absolutely necessary in the first place.

  • Could you elaborate which other styles you evaluated?
    – bjornte
    Jun 10, 2016 at 12:33
  • For my personal use, Wikipedia’s support of entering cells one line at a time would be beneficial (for tables where there will be substantial amounts of information per row). In my limited testing, GitHub flavoured Markdown does not support this. Can you confirm if this is the case? Do you have experience as to whether this is a common need (beyond Wikipedia)? I just have opinions and personal preference to work with; quantitative data would be great. …hmm, perhaps we could get the thread participants over at Commonmark to vote?
    – bjornte
    Jun 10, 2016 at 12:42
  • It was done a few years ago, so I can't recall 100% all of the other styles we tested. However, html, xml, and Wikipedia's layout were among them. Our testing was not for longer content in a cell, so that is a limitation in our results. However, my gut says that if you want substantial content in each cell, Wikipedia's method would be better. However it would be at the expense of readability for simpler content.
    – JohnGB
    Jun 10, 2016 at 13:17

I’m writing most of my documents in Markdown ... one of the biggest caveats being lack of native support for tables

MultiMarkdown supports tables like this (as per GitHub flavored Markdown)

| Heading1 | Heading2 |
| Apples   |  27      |
| Oranges  |  31      |

Some MultiMarkdown processors allow elaborations on this theme.

Since switching to Markdown, I rather miss the table style from Grutatxt which allows multi-line table cells. This is really useful for tables where cells contain long paragraphs of descriptive text.

| Band Name      | Album Name           | Number of |
|                |                      | Songs     |
| Dead Can Dance | A Passage in Time    | 16        |
| Bel Canto      | White-Out Conditions | 10        |
| Depeche Mode   | Speak and Spell      | 16        |
| Love Spirals   | Temporal             | 13        |
| Downwards      |                      |           |

Grutatxt only supports column-spanning, not row-spanning of cells.

I’m wondering if anyone has actually researched the subject, and if yes, was a conclusion reached? Is there a best practice the UX community could propose for CommonMark?

Would it be unacceptable to support several different table markup styles? Each has their advantages.

Pandoc supports multiple styles and uses a terminology that I find helpful

  • Simple tables
  • Multiline tables
  • Grid tables
  • Pipe tables

The goal of the Creole project is a standard syntax for wikis.

In the finished Creole 1.0 spec, this is the markup for tables:

|=Heading Col 1 |=Heading Col 2         |
|Cell 1.1       |Two lines\\in Cell 1.2 |
|Cell 2.1       |Cell 2.2               |
  • All cells are separated by single pipes.
  • Leading spaces are permitted before the first cell of a row and trailing spaces are permitted at the end of a line.
  • The ending pipe is optional.
  • Equal sign directly following pipe defines a header.
  • Headers can be arranged horizontally or vertically.

On the Tables page it says that it’s only a "very basic table syntax, with no alignment", and it "only contains a notion for creating headings and forced line breaks". Its discussion page might contain some valuable insight. (The page Complex Tables Proposal does not contain much.)

On the page List Of Table Markups they listed which table syntaxes various wikis use. On the page Tables Reasoning they compared/grouped the syntaxes (it doesn’t contain many details though).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.