How to Make Collapsible Markdown Tables

Extensive API parameter schemas, multi-benchmark performance runs, and exhaustive database migration logs can quickly overwhelm GitHub Pull Requests and README files. Wrapping your Markdown table in semantic HTML5 <details> and <summary> tags creates clean, native, zero-JavaScript accordions that keep documentation concise without sacrificing depth.

Quick Reference: Anatomy of a Collapsible Table

<details> <summary>Click to view Benchmark Results</summary> | Benchmark | V1 Baseline | V2 Refactor | Delta | | :-------- | :---------: | :---------: | :---: | | Latency | 142 ms | 28 ms | -80% | | Memory | 512 MB | 140 MB | -72% | </details>

1. <details> WrapperEncloses the collapsible section in standard HTML5.

2. <summary> TitleDefines the clickable toggle header and toggle arrow.

3. The Blank LineMandatory blank space before the table header row.

The Golden Rule: The Blank Line Requirement

The single most common bug developers report on GitHub is that their table renders as raw, ugly pipe characters inside the dropdown. According to the CommonMark specification, when a parser encounters an HTML block tag like <summary>, it remains in pure HTML mode.Only an empty blank line signals to the parser that HTML block mode has ended and that subsequent lines should be parsed as Markdown:

❌ Broken (Missing Blank Line)

<details>
<summary>View Changelog</summary>
| Version | Changes |
| :------ | :------ |
| v2.0.0  | New API |
</details>

GitHub renders literal pipe characters | Version | Changes | without building a table.

✅ Working (With Blank Line)

<details>
<summary>View Changelog</summary>

| Version | Changes |
| :------ | :------ |
| v2.0.0  | New API |
</details>

The blank line triggers GFM table parsing, rendering a clean HTML table upon clicking.

Default Open State (<details open>)

By default, a <details> element is closed upon page load. If you want the table to be visible immediately—allowing readers to optionally collapse it to save scroll space—add the boolean attribute open:

<details open>
<summary><b>API HTTP Status Codes</b> (Click to collapse)</summary>

| Status Code | Meaning | Common Cause |
| :---------: | :------ | :----------- |
| 200 | OK | Successful GET/POST request |
| 401 | Unauthorized | Missing or expired JWT Bearer token |
| 429 | Rate Limited | Exceeded 100 requests per minute |

</details>

Rich Formatting in <summary> Headers

You are not limited to plain text in the accordion title. You can include bold tags (<b>), code chips (<code>), emojis, and item counters:

<details>
<summary>🚀 <b>Test Suite Execution Summary</b> (<code>42 passed</code>, <code>0 failed</code>)</summary>

| Suite Name | Tests | Duration | Coverage |
| :--------- | :---: | :------: | :------: |
| Auth E2E   | 14    | 3.2s     | 98.4%    |
| Table Engine Unit | 28 | 0.8s  | 100.0%   |

</details>

Interactive Live Browser Simulation

🚀 Test Suite Execution Summary (42 passed, 0 failed)

Suite Name	Tests	Duration	Coverage
Auth E2E	14	3.2s	98.4%
Table Engine Unit	28	0.8s	100.0%

Common Pitfalls & Broken vs Fixed Examples

Pitfall 1: Indenting the Table Rows Inside <details>

❌ 4-Space Indentation<details> <summary>Specs</summary> | CPU | RAM | | :-- | :-- | | 4c | 16G | </details>Result: Indenting 4 spaces triggers Markdown code block rules! The table appears inside a raw grey box.

✅ Flush Left (0 Spaces)<details> <summary>Specs</summary> | CPU | RAM | | :-- | :-- | | 4c | 16G | </details>Result: Renders as a true, styled responsive table.

Pitfall 2: Forgetting the Closing </details> Tag

Platform Compatibility Matrix

Platform / Tool	Support Level	Notes & Limitations
GitHub (GFM)	Full Support	Native accordion toggle across READMEs, PRs, and Issues. Requires blank line after </summary>.
GitLab (GLFM)	Full Support	Supported in Merge Requests, Wiki docs, and Markdown snippets.
Obsidian	Full Support	Renders collapsible blocks in both Live Preview and Reading View.
Bitbucket	Partial Support	Supported in modern cloud pull requests; some on-premise server versions sanitize HTML.
Azure DevOps	Partial Support	Requires HTML table syntax inside details in legacy wiki pipelines.
VS Code	Full Support	Built-in markdown preview natively expands and collapses <details> blocks.

Frequently Asked Questions

Why is my Markdown table rendering as raw text with pipes inside <details>?

You almost certainly omitted the mandatory empty blank line between the closing </summary> tag and the start of your table header (| Col 1 | Col 2 |). In CommonMark and GFM specifications, a blank line is required to transition the parser from raw HTML block mode back into Markdown parsing mode.

Does <details> work in GitHub README.md files or only in Pull Requests?

It works everywhere across GitHub! You can use <details> and <summary> in repository README.md files, Wiki pages, Issue comments, Pull Request descriptions, and GitHub Discussions.

How do I make the collapsible table open and expanded by default?

Add the "open" boolean attribute to the opening tag: <details open>. The table will be expanded when the page loads, allowing readers to collapse it if they want to reduce vertical scrolling.

Can readers use Ctrl+F or browser search to find text inside a collapsed table?

Yes! Modern browsers (Chrome, Edge, Safari, Firefox) automatically expand a <details> element when a user searches for text matching inside it using standard in-page search (Ctrl+F or Cmd+F).

Can I nest multiple collapsible tables inside one another?

Yes. You can nest child <details> elements inside parent <details> elements to create hierarchical documentation trees (e.g. API V2 -> Authentication Endpoints -> Error Matrix). Always remember to include a blank line after each nested </summary>.

Related Markdown Table Syntax Guides

Line Breaks (<br>)

Multi-line text and bullet lists in cells.

Column Width Control

Control wrapping, min-width, and padding.

Checkboxes & Tasks

Interactive task lists and status badges.

Wrap Any Table in <details> with One Click

Our free table generator has a built-in "Collapsible <details>" export option that formats everything with proper blank lines automatically.

Open Table Generator