Tables with cells that contain block elements

[colleenmcginnis]

Related to #112 (comment) (but opening a new issue for visibility)

Describe the bug

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.

Expected behavior

See above...

Steps to reproduce

See above for examples and ways to search for additional affected tables.

Tooling

• docs-builder
• migration tooling
• I'm not sure

[colleenmcginnis]

We'll also need to make sure we remove any line breaks inside table cells:

Local link

[colleenmcginnis]

Also, if you're using block elements in table cells, internal links are also not migrated like here: