[Feature Request]: Improved ES|QL examples output table formatting

[craigtaverner]

Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

In the ES|QL docs, the examples have a query followed by the expected output. In the 8.x docs the output table is nicely formatted monospace, and clearly attached to the query, while in the new docs the table is not using a monospace font, and is visibly separated from the query. I read the docs on tables at https://elastic.github.io/docs-builder/syntax/tables/, and there does not appear to be any formatting option support like we used in asciidoc for this.

This is an example from 8.x:

And this is an example from main (using docs-builder built locally on the 11th March):

In 8.x we achieved this formatting in asciidoc with:

To count the number of rows, use `COUNT()` or `COUNT(*)`
[source.merge.styled,esql]
----
include::{esql-specs}/docs.csv-spec[tag=countAll]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/docs.csv-spec[tag=countAll-result]
|===

For main, we cannot use include like this, but we have written our own include feature as part of the docs generating process, so the markdown looks like:

To count the number of rows, use `COUNT()` or `COUNT(*)`

\```esql
FROM employees
| STATS count = COUNT(*) BY languages
| SORT languages DESC
\```

| count:long | languages:integer |
| --- | --- |
| 10 | null |
| 21 | 5 |
| 18 | 4 |
| 17 | 3 |
| 19 | 2 |
| 15 | 1 |

Proposed Solution

The missing piece is something similar to the line [%header.monospaced.styled,format=dsv,separator=|] from the asciidoc table. We don't need that exact set of arguments, but something that would allow us to achieve:

• Monospaced font
• Visible attachment of the table to the query:
  • remove separation
  • perhaps add a border so it is clear they are attached

Making it looks identical to the older docs is not required, but making it look like a results table, not a generic text table, is required.

Perhaps something like:

::::{table} font=monospaced padding=0 border=1
| count:long | languages:integer |
| --- | --- |
| 10 | null |
| 21 | 5 |
| 18 | 4 |
| 17 | 3 |
| 19 | 2 |
| 15 | 1 |
::::