Collapsible Sections in Markdown

Basic details and summary syntax

Wrap the hidden content in <details>, and put a <summary> element first to act as the label. Readers see only the label with a small arrow until they click it.

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

Hidden content goes here. **Markdown** works
because of the blank line above.

- Lists
- Images
- Code blocks

</details>

Why the blank line matters

Under CommonMark rules, an HTML block runs until the next blank line, and everything in it is passed through as raw HTML. Without a blank line after </summary>, the text that follows is still part of that HTML block, so **bold** and - list markers appear literally. The blank line ends the HTML block and switches the parser back to Markdown. Put another blank line before </details> for the same reason.

<details>
<summary>Broken</summary>
**This stays literal**
</details>

<details>
<summary>Fixed</summary>

**This renders bold**

</details>

Open by default

Add the open attribute to show the content expanded when the page loads. Readers can still collapse it.

<details open>
<summary>Installation steps</summary>

1. Download the file
2. Run the installer

</details>

Code blocks and nested sections

Fenced code blocks work inside details as long as they are surrounded by blank lines. Sections can also be nested, which is handy for long changelogs or FAQ lists in a README. Do not indent the content by four spaces, because indentation turns it into an indented code block.

<details>
<summary>Show the config</summary>

```json
{ "theme": "github", "pageSize": "a4" }
```

<details>
<summary>Advanced options</summary>

Nested content.

</details>

</details>

When to collapse content

Collapsible sections keep a README or issue scannable without deleting detail. Good candidates are long logs and stack traces in bug reports, full configuration files, optional platform-specific install steps, screenshots that support but do not drive the text, and the answers in an FAQ. Keep anything a reader needs on a first pass (the summary, the quick-start command, warnings) visible, because many readers never expand a section.

<details>
<summary>Full error log</summary>

```text
Error: ENOENT: no such file or directory
    at Object.openSync (node:fs:601:3)
```

</details>

Where collapsible sections work

Support depends on whether the renderer allows raw HTML. Platforms that strip HTML need their own feature instead.

Common pitfalls

Missing blank lines are the number one cause of broken dropdowns. Others: putting text before <summary> (the label must come first), using Markdown formatting inside the summary itself (it sits inside the HTML block, so use <b> or <code> tags there instead), and indenting the content, which creates a code block. Also remember that in PDF or print output there is nothing to click, so collapsible content is a web-only feature.