[Discuss] Tables

[bmorelli25]

Conversion

Tables are rendered as:

```{table}
:width: auto
| <header> | <header> | <header> | ... |
| -------- | -------- | -------- | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|   ...    |   ...    |   ...    | ... |
```

[Mpdreamz]

We support this table syntax but also just the regular GitHub flavored style which would be a bit cleaner in this case?

e.g just:

| <header> | <header> | <header> | ... |
| -------- | -------- | -------- | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|  <text>  |  <text>  |  <text>  | ... |
|   ...    |   ...    |   ...    | ... |

They would render better on Github too.

Sidenote: I personally dread creating tables in markdown even when my editor helps me so i'd still like a specialized syntax for this e.g

```{code-table} <path to yaml_json>
:columns: prop1, prop3, prop4
```

and maybe revisit #17

[bmorelli25]

Added your table suggestion to #160. I'm going to keep this issue open for now as there are likely some edge cases with tables that we won't see until the bug bash.

[lcawl]

I think you're already aware of this one, but the table in https://www.elastic.co/guide/en/elasticsearch/reference/8.17/modules-cross-cluster-search.html#ccs-supported-configurations was brought up as one that has a poor user experience in the old system. It's sourced from https://github.com/elastic/elasticsearch/blob/8.17/docs/reference/search/search-your-data/ccs-version-compat-matrix.asciidoc

If it's going to be equally poor in the new system, IMO we ought to confirm what's the recommended table behavior in the new system (maximum rows or columns, support for spanning, etc) then clean these up during our migration (or pre-migration if we have advice by then). Off the cuff, for this particular table we could split it into multiple smaller tables or worst case just summarize it as a list instead of a table. Generally moving toward simplicity and smaller bites of info seems like the right path for this stuff.

[colleenmcginnis]

I'm seeing a couple issue with tables, but probably the most concerning is when an AsciiDoc table contains cells that contain multiple block elements. I don't necessarily think we should support this in docs-builder, but we should definitely have a plan for handling these situations because it's a pretty common pattern across docs, and it makes content very difficult to read.

Example: Cells containing admonitions

AsciiDoc	doc-builder
Link	Link

To get a sense of the scope of this issue, you can search some AsciiDoc docs for (^| )a\| (though that probably won't capture all of the cells). Here's what I got when I checked a few repos:

• elastic/elasticsearch: 10 mentions in 4 files
• elastic/kibana: 102 mentions in 12 files
• elastic/observability-docs: 211 mentions in 29 files

If we want writers to simplify tables and/or un-table-ify content in complex tables more broadly, we can use this regular expression to capture more formatted cells in AsciiDoc files: ( |^)((\d+)|(\.\d+)|(\+|\*)|([\^\.<>]+)|(a|d|e|h|l|m|s))+\|. This should catch spanning columns/rows, duplicating cells, and formatting cells.

[theletterf]

Is #23 related?