All docs: Improve table experience

[zlovatt]

Issue:

The standard markdown tables (below) work for simple use cases, however when trying to add in rich content (lists, code blocks, line breaks) they're annoying to use – the only solve in vanilla markdown is to add html tags directly to the tables.

This makes the experience nicer to read, but worse for the author.

Examples:

Basic MD table

source:

| Title A  | Title B  |
| -------- | -------- |
| Item 1.A | Item 1.B |
| Item 2.A | Item 2.B |

rendered as:

Title A	Title B
Item 1.A	Item 1.B
Item 2.A	Item 2.B

Basic MD table with line breaks

source:

| Title A  |              Title B              |
| -------- | --------------------------------- |
| Item 1.A | Item 1.B<br/><br/>Item 1.B Line 2 |
| Item 2.A | Item 2.B                          |

rendered as:

Title A	Title B
Item 1.A	Item 1.B Item 1.B Line 2
Item 2.A	Item 2.B

Basic MD table with list

source:

| Title A  |                      Title B                       |
| -------- | -------------------------------------------------- |
| Item 1.A | <ul><li>Item 1.B</li><li>Item 1.B Line 2</li></ul> |
| Item 2.A | Item 2.B                                           |

rendered as:

Title A	Title B
Item 1.A	Item 1.B Item 1.B Line 2
Item 2.A	Item 2.B

Solution

Add in the markdown_grid_tables markdown extension.

This lets us use grid tables instead, in which you can better specify the number of markdown rows in each cell– much better for authoring, and doesn't impact the reading experience.

The downside is that it's a second table format to conditionally use (but this can be clarified in a style guide doc in the contribution guide).

Would need to add this extension into:

• mkdocs.yml
• requirements.txt

Examples

Basic MD table

source:

+----------+----------+
| Title A  | Title B  |
+==========+==========+
| Item 1.A | Item 1.B |
+----------+----------+
| Item 2.A | Item 2.B |
+----------+----------+

rendered as:

Title A	Title B
Item 1.A	Item 1.B
Item 2.A	Item 2.B

Basic MD table with line breaks

source:

+----------+-----------------+
| Title A  |     Title B     |
+==========+=================+
| Item 1.A | Item 1.B        |
|          |                 |
|          | Item 1.B Line 2 |
+----------+-----------------+
| Item 2.A | Item 2.B        |
+----------+-----------------+

rendered as:

Title A	Title B
Item 1.A	Item 1.B Item 1.B Line 2
Item 2.A	Item 2.B

Basic MD table with list

source:

+----------+-------------------+
| Title A  |      Title B      |
+==========+===================+
| Item 1.A | - Item 1.B        |
|          | - Item 1.B Line 2 |
+----------+-------------------+
| Item 2.A | Item 2.B          |
+----------+-------------------+

rendered as:

Title A	Title B
Item 1.A	Item 1.B Item 1.B Line 2
Item 2.A	Item 2.B

[zlovatt]

Note: All repos now have access to markdown_grid_tables via docsforadobe-mkdocs-config -- but some guides still need a pass to integrate the new tables & update syntax to fix the above issues

[zlovatt]

Closing; completed.