Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

List table (:::list-table)

There are two ways to render a table:

  1. list-table directive

    Markdown
    :::list-table

    - - header1
    - header2
    - - item1
    - item2

    :::
  2. 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:

Markdown
:::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

  • 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

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

line2

row2

bolded text

header1

header2

row1

line1

line2

row2

bolded text

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):

Markdown
::::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

Feature

Availability

Unity Catalog

All clouds

S3 external location

AWS only

note

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.