Tables in pure Markdown

Column span only occurs if the pipes are adjacent. In your example you would just have a normal empty cell in 3C because of the whitespace between the pipes.

Sweet! Thanks. Sounds like a pretty solid solution.

This is basically a subset of what I suggested in my comment
https://talk.commonmark.org/t/tables-in-pure-markdown/81/134. I’m glad to
hear it has been working well for your users.

In addition to row/colspans, my suggested syntax included:

  • syntax for column alignments
  • a way for multiple lines to be added to a cell, allowing
    block-level constructs like lists and code blocks

I think these are both important. But getting the details right about how the
rowspan syntax works with the cell continuation syntax might be a bit tricky.

Other things people have requested:

  • syntax for row headers (not just column headers)
  • syntax for multiple header rows
  • cell-level alignment
  • syntax for specifying relative column widths
  • syntax for captions

@aoudad’s comment has a lot of nice suggestions for these:
https://talk.commonmark.org/t/tables-in-pure-markdown/81/145.

In pandoc people have also requested these features:

  • intermediate header rows (not just at the top)
  • table footer

It’s very tricky to figure out what is the right level of complexity to
suport.

Actually, I think the table syntax that is most compatible with the Markdown
philosophy of prioritizing source readibility is grid tables:
https://pandoc.org/MANUAL.html#extension-grid_tables. Pipe tables look
increasingly like line noise the more features are added, while grid tables
look just like tables. But grid tables seem quite unpopular due to the need to
align columns.

1 Like

This is basically a subset of what I suggested

Yep that’s where I got most of the structure from. It seemed the “cleanest” out of everything I saw, and was easy to lay over the top of existing GFM standard tables without breaking what is already out there.

As for your other items:

  • syntax for column alignments

My syntax allows column alignments following the GFM standard of colons and dashes.

  • a way for multiple lines to be added to a cell

My syntax simply concatenates adjacent row-spanned cells together with a space. This allows the user to use all of the vertical space in a row-spanned group but yes, it does not allow multiline blocks.

Would it be worth supporting pipe tables only for simple cases? If your table gets to a certain level of complexity and is becoming unreadable it is probably a good idea to switch from pipe to grid tables.

This would be line with other Markdown features, for example setext headings are only supported for h1 and h2, requiring the writer to switch to atx style for h3-6 headings.

Can you share the data and or anecdotes behind that observation?

Can you share the data and or anecdotes behind that observation?

I don’t have data, this is just my memory of conversations going back many years.

Basically there’s a split in the Markdown community between people who use Markdown for long-form writing (documentation, articles, books) and those who use it mainly for things like Reddit or Stack Overflow comments. For the latter, grid tables are a problem because they are working in text boxes which often use proportional-spaced fonts, so lining anything up is next to impossible.

2 Likes

I assume when you say block-level, you’re excluding just chunking an HTML <br> in the table to create a newline - this works on SO/SE, which makes for useful formatting in tables even without bullets.

I’ve used grid tables on SO/SE (posts, not comments)… the only way they work is if you put them in a code fence so that they’re fixed width. It does work, and we did it for years before we implemented markdown tables… but my thumbs definitely got tired from all of the spaces you needed to use to keep everything aligned.

I will say, there were some perks to it that you can’t really replicate in MD tables.

  • You could align things pretty much wherever you wanted. Want the header to be centered and the column content to be right aligned? No problem, just change the spacing.
  • Looks pretty in a fixed-width preview. Trying to review a MD table without a live preview is… not fun (for me, anyway). If your text entry pane is already in fixed width anyway, what you see is what you get - without fancy programming and no need to check your preview.

So, they’re not terrible and they do have some functionality that’s nice.

(Separately from the above)

One of the biggest asks we’ve seen from community members (and one of my biggest frustrations) has been the ability to control the column width which is separate than column span. I don’t know that I’ve seen much discussion of this and I’m not sure whether there’s a viable solution to allow people to call out a max column width, for example (either in percentages or px).

(Separately from the above)

One of the biggest asks we’ve seen from community members (and one of my biggest frustrations) has been the ability to control the column width which is separate than column span. I don’t know that I’ve seen much discussion of this and I’m not sure whether there’s a viable solution to allow people to call out a max column width, for example (either in percentages or px).

Pandoc does have a system for this.

For grid, simple, and multiline tables, widths are calculated based on the widths in the source.

For pipe tables, if one of the lines extends beyond 72 columns (configurable), then relative widths are calculated based on the widths of the separator lines.

1 Like

Hi all!

I hope it helps, I saw this amazing discussion and this would be my simple idea to help. I think it could be something like this:

image

pros

  1. You can add csv content inside `` table
  2. many systems csv files which would be easy to add with this syntax

A markdown editor might offer to import CSV, TSV, … files into markdown tables, but those data formats should not become a valid table syntax themselves, because their human readability is severely impaired.

2 Likes

this was a starter idea, my last idea would be something like this:

{| 
  header1, header2, header3, header4 ... 
 |} {| 
  value1 header1,  value 2 header1 ... 
  value1 header2,  value 2 header2 ... 
  value1 header3,  value 2 header3 ... 
  value1 header4,  value 2 header4 ...  
|}

based on this:

{|
! Header !! Another header
|-
| field 1 || something
|-
| field 2
| something else
|}

I don’t know if the syntax is good or valid, but I wanted to know your opinion

Hi - what’s the status of this feature? Is there something people are using to get this to work? Thanks.

@blakew the status is that noone is going to implement this anytime soon. They just dont know how…

2 Likes

It’s not in the spec, but there are plenty of commonmark implementations out there that offer table extensions compatible with what GitHub uses.

Hello everyone! :wave:

Here’s an idea I had over the weekend.

,,,
header1 , header2 , header3
item1   , item2   , item3
item4   , item5   , item6
,,,

Pipes work too.

,,,
header1 | header2 | header3
item1   | item2   | item3
item4   | item5   | item6
,,,

I created a repo with all the deets.

2 Likes

What would your idea’s advantages be over the following?

``` csv
header1 , header2 , header3
item1   , item2   , item3
item4   , item5   , item6
```

By sticking with existing fenced code syntax, it degrades gracefully under generic Markdown processing.

(There’s a related discussion about whether fenced code blocks can be interpreted, processed or executed.)

2 Likes

:thinking: Hmm… that’s a good question.

  1. Primarily, it won’t conflate the 2 features. Tables vs fenced code blocks, when is something “common”? - #11 by chrisalley
  2. The csv fenced code block removes the option to display the fenced contents as plaintext with highlighting.
1 Like

Chiming into this thread here to note that i’ve recently extended my team’s fork of cmark-gfm to add basic support for row- and column-span: add support for colspan/rowspan in tables by QuietMisdreavus · Pull Request #46 · apple/swift-cmark · GitHub

I pulled the syntax ideas from this thread, so thanks for having this discussion here. I didn’t add things like row headers or multi-line headers, since i wanted to keep the implementation fairly unobtrusive and i figure that those can be added on independently.