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.