List table (:::list-table)

↑ Docs content model

The :::list-table directive renders a table from a list-based syntax, which supports complex nested structures and multi-line content that GitHub Flavored Markdown (GFM) tables can't.

When to use

Use :::list-table for tables with multi-line cells, nested lists, or other directives inside cells, and for card-styled link grids (style='cards'). Use a plain GFM table for simple, single-line content.

Technical details

There are two ways to render a table:

1. The list-table directive:

   Markdown

   :::list-table
   
   - - header1
     - header2
   - - item1
     - item2
   
   :::

2. A GitHub Flavored Markdown (GFM) table:

   Markdown

   | Header 1 | Header2 |
   | -------- | ------- |
   | item1    | item2   |

The key differences are that GFM tables are meant for single-line content (multiple lines require <br/><br/> tags), and non-text directives are not supported in them. Use the list-table directive for complex nested structures or multi-line content.

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 (each list in the directive to contain a list with exactly 2 elements). The table's header row is then ignored, and each subsequent row renders 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 render exactly like regular list-tables (including the header row) — so it's important to still provide a header row with appropriate labels.

Rules

• Open with :::list-table and close with :::.
• For style='cards', every row must have exactly 2 columns, and the first column must be a link.
• Always provide a meaningful header row, since Azure renders card list-tables as regular tables (header included).

Style

• Prefer a GFM table for simple content; reserve the list-table directive for cells that need lists, multiple paragraphs, or nested directives.

Template

Markdown

:::list-table

- - Header 1
  - Header 2
- - Row 1, cell 1
  - Row 1, cell 2

:::

Examples

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

• • Card 1 title
  • Card 1 body
• • Card 2 title
  • Card 2 body
• • Card 3 title
  • Card 3 body

Used in

Content atoms appear in any page section. List tables (especially the card style) are the backbone of landing pages and of Additional resources.