[Markdown] Decide what to do with tables

[wbamberg]

GitHub-Flavored Markdown supports a table syntax: https://github.github.com/gfm/#tables-extension- , but it's quite limited.

As far as I can tell, the table:

• must have a header row
• must not have a header column
• cells can't contain Markdown block elements
• cell contents can't span multiple lines

This means a lot of our tables won't be representable using this syntax.

I can think of three main options here:

1. use GFM syntax when we can, and HTML tables the rest of the time
2. just use HTML tables all the time
3. use some other table syntax

I'm not keen on (3), because I think we should stay with GFM as much as we can and not invent or import extra syntaxes unless we really have to. I think I like (1) best, but it depends a bit on how many tables we have and what they are like.

So I did a bit of digging into our use of tables in the JS docs.

• out of 922 pages in JavaScript
• we have 872 tables
• of which 774 are spec tables

Given @Elchi3 's work over in mdn/yari#3518, it looks like we'll be able to generate spec tables from data quite soon (just as we already do for compat tables. So probably we would only have to worry about the 98 tables that aren't spec tables.

I did a bit more digging into this: https://docs.google.com/spreadsheets/d/1PGty8FHBPaShQdnO8mWBFAcEeddCpOXuoTkUhezAY80/edit#gid=0 .

In summary, of 98 (non spec table) tables in the JS docs:

• 40 could be represented using GFM syntax
• 24 use captions, otherwise could be represented using GFM syntax
• 15 use a column heading
• 18 use block elements in cells, such as lists
• 1 is just complex

If we think it's OK to stop using captions we can in theory represent about 2/3 of the tables using GFM syntax. Our own docs recommend using captions for tables: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#captions meaning this might be a stretch (but we don't as a rule use captions at the moment anyway, so...).

The third that are using column headings or block elements would have to use raw HTML.

As an aside, pages that use complex tables are pleasingly rare, and where the occur, the page would be made much better by simplifying them. See for example #4133.

[hamishwillee]

To me option 1 is a no brainer - use GFM table syntax where possible, HTML otherwise, and hope that in future more of the HTML tables can be auto-generated.

But even within GFM there is some variant that we should lock down. E.g.

• There are two table syntaxes - one that creates a full table-like scaffolding around the cells, another which just indicates the columns. The second format is much easier to edit.
• You can only do headings across the top "formally" but you can fake a horizontal header "as well" using Bold on the first column. Do we recommend that?

[wbamberg]

To me option 1 is a no brainer - use GFM table syntax where possible, HTML otherwise, and hope that in future more of the HTML tables can be auto-generated.

+1

But even within GFM there is some variant that we should lock down. E.g.

• There are two table syntaxes - one that creates a full table-like scaffolding around the cells, another which just indicates the columns. The second format is much easier to edit.

Can you show me an example of the first format? The GFM spec only talks about the second AFAICS.

• You can only do headings across the top "formally" but you can fake a horizontal header "as well" using Bold on the first column. Do we recommend that?

Do you mean "vertical header"?

I wouldn't, no, because it's not semantic HTML.

[hamishwillee]

I wouldn't, no, because it's not semantic HTML.

This is going to give you/us some headaches long term. Because I can almost guarantee that people will use this kind of approach to do tables once we support markdown ("if you build this we will come").

This is the minimal syntax (you can also use colons on the second line to control column alignment)

Heading 1 | Heading 2 | Heading 3
 --- | --- | ---
text 1    | text 2    |  thingy 
text 1    | text 3    | text 1 

This is the fullest syntax

| Heading 1 | Heading 2 | Heading 3 |
|-----------|-----------|-----------|
| text 1    | text 2    |   thingy  |
| text 1    | text 3    | text 1    |

I should note that in the full syntax you don't need to have the precise alignments of columns etc, but if you don't then it is a bit irritating to look at. The problem with the minimal format is some renderers do not recognise first-column cell with empty space (you have to insert a non-breaking space HTML char.

Yes, I meant vertical header sorry.

[ddbeck]

I wanted to endorse the "use GFM syntax when we can, and HTML tables the rest of the time" option. 👍

For the table source appearance problem, the ideal thing would be to use Prettier (or similar) to automatically format and enforce the full syntax. Whether we can do that in practice depends on us not adopting any Prettier-unfriendly changes to CommonMark/GFM (e.g., adopting kramdown-style block attributes would preclude this option).

For the horizontal header problem, I think that's on PR reviewers to block, right? We can already do blasphemous things in HTML, but it's my hope that someone reviewing my PR would tell me to cut it out. 😄

[wbamberg]

I wanted to endorse the "use GFM syntax when we can, and HTML tables the rest of the time" option. 👍

For the table source appearance problem, the ideal thing would be to use Prettier (or similar) to automatically format and enforce the full syntax. Whether we can do that in practice depends on us not adopting any Prettier-unfriendly changes to CommonMark/GFM (e.g., adopting kramdown-style block attributes would preclude this option).

That's interesting, I was talking about using Prettier with @Gregoor today. I agree that being able to use it would be a big advantage.

For the horizontal header problem, I think that's on PR reviewers to block, right? We can already do blasphemous things in HTML, but it's my hope that someone reviewing my PR would tell me to cut it out. 😄

Yes.

[jpmedley]

My vote is for option 1.

[hamishwillee]

Sounds like we're all in agreement. Worth updating the spec and closing this?

[wbamberg]

Yeah, I'm working on it, this will be the next one to close.

[wbamberg]

I've updated #3350 (comment) with some guidance for the converter about converting tables, so I'm going to close this one.