It is recommended to use the order of | Default |Options|. The first impression after reading the current order is that Default is the value of Options rather than the header.

I also agree with @wmhn1872265132 that it might be better to replace the left and right column positions.

It is recommended to use the order of | Default |Options|. The first impression after reading the current order is that Default is the value of Options rather than the header.

Is this implication not an issue with these reversed? Wouldn't you get the impressions that "Options" is the value of "Default" rather than the headers.

I don't think so, because the default is more like one of the options, but there is rarely an option called an option

If you consider a linear reading order, that is, users do not use table navigation to read, then @wmhn1872265132's concerns should be valid.

Do we need to think about it, for similar options, do we really need to format it into a table? What are the advantages of using tables? Including the previous list style also seems to have caused some misunderstandings.

Before using the list style, did some users report that this was not stated clearly enough.

I understand and share the concern of @cary-rowen and @wmhn1872265132 regarding reading order, with "Options" coming before "Default" when reading with downArrow (or SayAll by the way).

Though, it's more logical to have first the information of the available options and then the default one.

I would also add that using columns is not very comfortable since it forces the user to use table navigation to read this 2x2 table. Instead, using rows to store the informations, the user could use either table navigation or just downArrow or SayAll. Moreover, visually, the layout may be quite ugly if the number and names of the options takes too much space. At last, in other materials where options are described, I tink it's alwas done in row, not in column, so people are used to this visual layout.

So my recommendation would be to use a table with the information in rows if possible, i.e.:

And, nice to have if possible, with the first column set as rows headers.

If horizontal layout is not technically possible, just use list instead:

• Options: Option 1, Option 2, Option 3
• Default: Option 2

Native markdown only supports one type of table: the first row is always column headers, there are no other headers.
The general workaround is to use raw HTML like you've done, but we'd prefer to avoid HTML is markdown docs.

We can try out an extended python markdown plugin like this one:
https://github.com/tableau-tables/python-tableau-parser

This extension doesn't seem to be maintained well.
Alternatively, we can create empty header rows, and hide them with CSS

Markdown table:

| . {.hideHeaderRow} | . |
|---|---|
| Options | Enabled, Disabled |
| Default | Disabled |

CSS

thead:has(tr > th.hideHeaderRow) {
  display: none;
}

HTML output:

<table>
<thead>
<tr>
<th class="hideHeaderRow">.</th>
<th>.</th>
</tr>
</thead>
<tr><td>Options</td><td>Option 1, Option 2, Option 3</td></tr>
<tr><td>Default</td><td>Option 2</td></tr>
</table>

Rendered HTML output (note no styling)

NVDA Output - note row numbers are wrong

Row 2, Column 1, Options
Column 2, Enabled, Disabled
Row 3, Column 2, Default

What will be the syntax?

I am a bit concerned that the translators will have to copy/paste table headers row in the md file, making a md file less easy to read. Or won't this header string appear at all if the documentation is split in CrowdIn? How do these tables behave when the .md file is provided and split for translation?

Alternatively, I wonder if the list is not just simpler. Have you considered replacing the table by a list as suggested in #16083 (comment)?

Also, @seanbudd, you wrote:

The general workaround is to use raw HTML like you've done, but we'd prefer to avoid HTML is markdown docs.

Fully agree with you. The table in my example was meant to illustrate the result I want to achieve in the HTML User Guide; the way these tables were produced are not to be considered in this example.

Alternatively, I wonder if the list is not just simpler. Have you considered replacing the table by a list as suggested in #16083 (comment)?

+1 to this.