Markdown Collapsible Section: Details, Toggle & Accordion

What Is a Collapsible Section?

A collapsible section is a block of content that starts hidden and expands when the reader clicks a label. It is not native Markdown syntax — it uses the HTML <details> element, a disclosure widget built into every modern browser.

Most Markdown renderers pass HTML through unchanged, so <details> works anywhere that allows inline HTML: GitHub, GitLab, VS Code preview, Obsidian, and desktop Markdown viewers like MDViewer.

Basic Syntax

A collapsible section needs three parts: an opening <details> tag, a <summary> label, and a closing </details> tag. Everything between </summary> and </details> is hidden until the reader clicks.

<details>
<summary>Click to expand</summary>

This content is hidden by default. It appears when
you click the summary label above.

</details>

The blank line after </summary> is critical. Without it, Markdown inside the block renders as literal text instead of formatted output. See the next section for why.

The Blank Line Rule

The most common mistake with collapsible sections is forgetting the blank line after </summary>. This is not a GitHub quirk — it comes from the CommonMark specification, section 4.6 (HTML blocks).

When a Markdown parser encounters an HTML block tag like <details>, it treats everything that follows as raw HTML until it hits a blank line. Only after that blank line does the parser switch back to processing Markdown syntax.

Broken: no blank line

<details>
<summary>Details</summary>
**This bold text** won't render.
- This list won't render either.
</details>

Result: the reader sees the literal characters **This bold text** and - This list instead of formatted content.

Working: blank line after summary

<details>
<summary>Details</summary>

**This bold text** renders correctly.
- This list renders too.

</details>

The blank line tells the parser: stop treating this as an HTML block, start processing Markdown again. Add another blank line before </details> as well for clean parsing.

Markdown Inside Collapsible Sections

With the blank line in place, all standard Markdown works inside a <details> block: bold, italic, lists, code blocks, tables, and links.

<details>
<summary>Configuration options</summary>

**Required settings:**

- `host` — server hostname
- `port` — defaults to `8080`

| Setting  | Default   | Description       |
|----------|-----------|-------------------|
| `host`   | localhost | Server address    |
| `port`   | 8080      | Listening port    |
| `debug`  | false     | Enable debug logs |

```bash
export HOST=0.0.0.0
export PORT=3000
```

</details>

Code blocks, tables, and lists all render correctly. This makes collapsible sections ideal for hiding lengthy reference material without cluttering the page.

Accordion Pattern

Stack multiple <details> blocks to create an accordion-style layout. Each section opens and closes independently.

<details>
<summary>Installation</summary>

Download from the releases page and run the installer.

</details>

<details>
<summary>Configuration</summary>

Copy the example config file and edit the settings.

</details>

<details>
<summary>Troubleshooting</summary>

Check the log file at `~/.app/debug.log` for error details.

</details>

Note: there is no native way to auto-close one section when another opens. Each <details> block is independent. If you need exclusive open/close behavior, you would need JavaScript or a framework-specific component.

Open by Default

Add the open attribute to make a collapsible section expanded when the page loads. The reader can still click to collapse it.

<details open>
<summary>This section starts open</summary>

The reader sees this content immediately. They can
click the summary to collapse it.

</details>

This is useful when one section contains the most important information and the rest are supplementary. The open attribute takes no value — its presence alone is enough.

Nested Collapsible Sections

You can place a <details> block inside another <details> block. This creates a hierarchical expand/collapse structure.

<details>
<summary>API Reference</summary>

Overview of all endpoints.

<details>
<summary>GET /users</summary>

Returns a list of all users. Accepts `limit` and
`offset` query parameters.

</details>

<details>
<summary>POST /users</summary>

Creates a new user. Requires `name` and `email`
in the request body.

</details>

</details>

Nesting works on GitHub, GitLab, VS Code, Obsidian, and MDViewer. Keep it to two levels — deeper nesting becomes hard to navigate.

Platform Support

On platforms that strip HTML, the content inside <details> either disappears or renders as unstyled text. Check your target platform before relying on collapsible sections.

Use Cases

Collapsible sections work well whenever you have content that some readers need but most can skip:

• Long log output — wrap build logs or error traces so they don’t dominate the page
• FAQ sections — let readers expand only the questions they care about
• Spoiler content — hide plot points, puzzle solutions, or exercise answers
• Optional configuration — show basic setup by default, tuck advanced options behind a toggle
• Lengthy code examples — keep the main text scannable while offering full source for those who want it
• Issue templates — GitHub issue templates often use collapsible sections for environment details and reproduction steps

A good rule of thumb: if the content is longer than a screen and only relevant to a subset of readers, wrap it in <details>.

FAQ

How do I create a collapsible section in Markdown?

Use the HTML <details> and <summary> tags. Write <details>, then <summary>Your label</summary>, leave a blank line, add your Markdown content, and close with </details>. The blank line after </summary> is required — without it, Markdown syntax inside the block won’t be processed. This works on GitHub, GitLab, VS Code, Obsidian, and MDViewer.

Why doesn’t my Markdown render inside details tags?

You need a blank line between </summary> and your Markdown content. Without it, the CommonMark parser treats everything inside the HTML block as raw HTML and won’t process Markdown syntax like bold, lists, or code blocks. This is defined in CommonMark spec section 4.6 (HTML blocks). Add a blank line after </summary> and another before </details> to fix it.

Can I create an accordion in Markdown?

Yes, by stacking multiple <details> blocks one after another. Each block opens and closes independently — there is no native way to auto-close one section when another opens. For exclusive accordion behavior (only one panel open at a time), you would need JavaScript or a framework component. For most documentation and README use cases, independent sections work fine.

Preview Your Markdown with MDViewer

MDViewer renders <details> blocks with a clean, styled disclosure widget — open any .md file from Finder and see collapsible sections working instantly. It also handles tables, Mermaid diagrams, and all standard Markdown. Lite is free; Pro adds editing, Git history, and PDF export for $9.99 one-time.

Requires macOS 13.0 or later. Intel and Apple Silicon.