How to Make a Collapsible Section in Markdown
By the MDConverter team · Updated · 2 min read
Quick answer
Markdown has no collapse syntax, so use HTML: wrap the content in <details> and put the clickable label in <summary>. Leave a blank line after </summary> and before </details> so the content inside is processed as Markdown. Add open to start expanded. It works on GitHub, GitLab, VS Code, most documentation sites and anywhere HTML is allowed.
Basic syntax
The <summary> text is always visible; the rest appears when the reader clicks it.
<details>
<summary>Installation steps</summary>
1. Download the installer
2. Run `setup.exe`
3. Restart your computer
</details>Installation steps
- Download the installer
- Run
setup.exe - Restart your computer
Expanded by default
Add the open attribute to show the content until the reader collapses it.
<details open>
<summary>Release notes</summary>
- **Added:** dark mode
- **Fixed:** login redirect
</details>Release notes
- Added: dark mode
- Fixed: login redirect
Code blocks and nested sections
Fenced code works inside, and <details> blocks can be nested — useful for long logs and FAQs.
<details>
<summary>Error log</summary>
```text
TypeError: Cannot read properties of undefined
at render (app.js:42:13)
```
<details>
<summary>Environment</summary>
Node 22, macOS 15
</details>
</details>Error log
TypeError: Cannot read properties of undefined
at render (app.js:42:13)Environment
Node 22, macOS 15
Formatting the summary line
Markdown inside <summary> is not processed by most renderers. Use HTML tags instead: <summary><b>Bold label</b></summary> or <summary><code>config.yaml</code></summary>. A heading inside the summary (<summary><h3>…</h3></summary>) works on GitHub but makes the arrow sit on its own line.
Alternatives in apps without HTML
- Obsidian: foldable callouts —
> [!note]- Titlestarts collapsed,> [!note]+ Titlestarts open. Headings can also be folded in the editor. - Discord:
||spoiler||hides text until clicked (inline only). - Notion: toggle blocks, created by typing
>at the start of a line.
Where <details> works
| App | Supported | Notes |
|---|---|---|
| GitHub | Yes | READMEs, issues, PRs, comments and wikis. |
| GitLab, Bitbucket | Yes | Supported in Markdown files and descriptions. |
| VS Code preview, MkDocs, Docusaurus | Yes | MkDocs Material also offers ??? collapsible admonitions. |
| Obsidian | Partly | Renders <details>, but Markdown inside it is not processed; use foldable callouts. |
| Reddit, Discord, Slack | No | HTML is not allowed. |
| Notion | No | Use a toggle block instead. |
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
| Markdown inside shows as raw text | Add a blank line after </summary> and before </details>. |
| The whole page after the section is hidden | You forgot the closing </details> tag. |
| Bold in the summary shows asterisks | Use <b> or <strong> inside <summary>. |
Tools for this
Frequently Asked Questions About Collapsible sections
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Related reading
- Markdown Blockquotes: Quotes, Nested Quotes and Callouts — Quote text with >, nest quotes, add lists inside, and make GitHub and Obsidian callouts.
- Markdown vs HTML: What Is the Difference? — How Markdown relates to HTML, what each can do, and when to mix them.
- How to Write Comments in Markdown — Leave notes in a Markdown file that never appear on the rendered page.