Collapsible Tables in Markdown with <details>

How do I make a collapsible table in Markdown?

Markdown has no collapse syntax of its own, but GitHub, GitLab and most renderers that allow HTML accept the HTML <details> element. Everything inside it except the <summary> is hidden until the reader clicks the summary line.

<details>
<summary>Supported versions (3 rows)</summary>

| Version | Released   | Status      |
| ------- | ---------- | ----------- |
| 3.2     | 2026-09-14 | Current     |
| 3.1     | 2026-05-02 | Security    |
| 3.0     | 2025-11-20 | End of life |

</details>

Mentioning the row count or the main takeaway in the summary (“3 rows”, “all tests pass”) tells readers whether it's worth opening.

Why the blank lines matter

Under CommonMark rules, a line starting with <details> opens an HTML block that runs until the next blank line, and everything in an HTML block is passed through as raw HTML. If the table follows </summary> directly, its lines are part of that HTML block and show up as plain pipes. The blank line ends the HTML block so the table is parsed as Markdown. The blank line before </details> keeps the closing tag from being read as part of the table.

Don't indent the table to make the source look nested: four or more spaces turn it into a code block.

Expanded by default, nesting and summary text

Expanded by default

Add open to show the table on page load while still letting readers collapse it:

<details open>
<summary>Supported versions</summary>

| Version | Released   | Status      |
| ------- | ---------- | ----------- |
| 3.2     | 2026-09-14 | Current     |
| 3.1     | 2026-05-02 | Security    |
| 3.0     | 2025-11-20 | End of life |

</details>

Nested sections

A <details> block can contain others, for example one table per operating system under a single heading. Each inner block follows the same blank-line rules:

<details>
<summary>Benchmarks</summary>

<details>
<summary>Linux</summary>

| Test  | Time   |
| ----- | -----: |
| Build | 41 s   |
| Tests | 2.3 min |

</details>

<details>
<summary>Windows</summary>

| Test  | Time   |
| ----- | -----: |
| Build | 58 s   |
| Tests | 3.1 min |

</details>

</details>

Formatting the summary

The summary line is HTML, so Markdown inside it isn't reliable. Use tags: <summary><b>Results</b> (12 rows)</summary> or <code> for file names. To make the summary look like a heading, put <h3> inside it; GitHub allows that, but it adds a heading to the page outline.

Obsidian, MkDocs, Jekyll and Quarto

Where plain <details> doesn't parse the table inside, each tool has its own collapse syntax:

Obsidian: foldable callouts

Obsidian shows the <details> toggle but doesn't render Markdown inside HTML, so the table appears as raw text. A callout with a - after the type is collapsed by default (+ starts it open), and tables inside callouts render:

> [!note]- Supported versions
> | Version | Status      |
> | ------- | ----------- |
> | 3.2     | Current     |
> | 3.0     | End of life |

MkDocs

Python-Markdown doesn't parse Markdown inside raw HTML. With Material for MkDocs, the usual choice is a collapsible admonition from pymdownx.details, with the table indented four spaces:

??? note "Supported versions"

    | Version | Status      |
    | ------- | ----------- |
    | 3.2     | Current     |
    | 3.0     | End of life |

To keep plain <details> markup, enable the md_in_html extension and add the markdown attribute:

<details markdown>
<summary>Supported versions</summary>

| Version | Status  |
| ------- | ------- |
| 3.2     | Current |

</details>

Jekyll and GitHub Pages

The same README can render on github.com and break on a GitHub Pages site: kramdown doesn't parse Markdown inside HTML blocks unless told to. Add markdown="1" (GitHub ignores the attribute):

<details markdown="1">
<summary>Supported versions</summary>

| Version | Status  |
| ------- | ------- |
| 3.2     | Current |

</details>

Quarto

Quarto's callouts take a collapse option, which works in HTML output:

::: {.callout-note collapse="true"}
## Supported versions

| Version | Status  |
| ------- | ------- |
| 3.2     | Current |
:::

Collapsible tables by platform

Common mistakes and fixes

No blank line after the summary

<details>
<summary>Supported versions</summary>
| Version | Status  |
| ------- | ------- |
| 3.2     | Current |
</details>

Fix it by adding an empty line after </summary> and before </details>, as in the first example.

Other things to check

• Unclosed tags. A missing </details> hides the rest of the document inside the section.
• Inside a list. Indent the whole block to the list item's content column, but by fewer than four extra spaces, or the table becomes code.
• The table itself is invalid. A collapsed table fails for the same reasons as any other. Check it with the table validator before wrapping it.

When to collapse a table, and when not to

Collapse tables that support the text but aren't needed to follow it: full benchmark results, long changelogs, option references, test matrices. Leave the main table of a page visible, because collapsed content is easy to miss, and say what's inside in the summary.

If the table is long because it's wide, a transposed table or a narrower column set may help more than hiding it; see column width. For the table rules themselves, see Markdown table syntax, and for a short key–value table that needs no header, see headerless tables.

Frequently asked questions