List table (:::list-table)
There are two ways to render a table:
-
list-table directive
Markdown:::list-table- - header1- header2- - item1- item2::: -
GitHub Flavored Markdown (GFM) Table
Markdown| Header 1 | Header2 || -------- | ------- || item1 | item2 |
The key differences are that GFM Tables are meant more for single line content (multi-lines require use of <br/><br/> tags),
and non-text directives are not supported. Use the list-table directive for complex nested structures or multi-line content.
Card styling
An additional feature available via the list-table directive is card styling (:::list-table{style='cards'}). This requires
each row of the table to have exactly 2 columns (i.e. each list in the directive to contain a list with exactly 2 elements).
The table's header row is then ignored, while each subsequent row is rendered as a card, with the
first column being the card's title (which must be a link) and the second column being the card's body. However, in
Azure docs, card styling is unavailable and such list-tables are instead rendered exactly like regular list-tables (including
the header row) - therefore, it's important to still provide a header row with appropriate labels.
Example:
:::list-table
- - header1
- header2
- - list1
- item
- item
- nested list:
- item
- item
list2
- item
- item
- Paragraph 1
Paragraph 2 - blank line required before and after.
- - **Another row**
- Another row of content
:::
| header1 | header2 |
| ------- | -------------------- |
| row1 | line1<br/><br/>line2 |
| row2 | **bolded text** |
:::list-table{style='cards'}
- - Header describing card titles
- Header describing card bodies
- - [Card 1 title](https://www.databricks.com)
- Card 1 body
- - [Card 2 title](https://www.databricks.com)
- Card 2 body
- - [Card 3 title](https://www.databricks.com)
- Card 3 body
:::
Output:
header1 | header2 |
|---|---|
list1
list2
| Paragraph 1 Paragraph 2 - blank line required before and after. |
Another row | Another row of content |
header1 | header2 |
|---|---|
row1 | line1 line2 |
row2 | bolded text |
-
- Card 1 title
- Card 1 body
-
- Card 2 title
- Card 2 body
-
- Card 3 title
- Card 3 body
Cloud-conditional rows
To show a row only on specific clouds, wrap it in a cloud directive. Because the cloud directive opens with three colons (:::aws), the enclosing list-table must open with at least four colons (::::list-table) so the cloud directive nests inside it instead of closing it. Surround the directive with blank lines, and use any cloud directive (:::aws, :::gcp, :::aws-gcp, and so on):
::::list-table
- - Feature
- Availability
- - :re[UC]
- All clouds
:::aws
- - S3 external location
- AWS only
:::
::::
You can wrap multiple consecutive rows in a single directive. On AWS builds the S3 external location row appears; on every other cloud it is omitted and the rest of the table renders unchanged. (The live output below reflects whichever cloud these docs were built for.)
Output:
Feature | Availability |
|---|---|
Unity Catalog | All clouds |
S3 external location | AWS only |
The blank lines around directives are maintained automatically by yarn prettier:fix; they stop prettier from folding the directive into the surrounding list, which would drop the table at build time. Keep them if you hand-edit.
Cloud-conditional rows are only supported in the list-table directive. Do not cloud-conditionalize rows in markdown tables that use the pipe syntax.