How to Make a Collapsible Section in Markdown

The <details> Syntax

There is no collapsible section in the Markdown spec, and there never has been. What every guide calls “Markdown collapsible sections” is the HTML <details> element, which works because CommonMark deliberately lets raw HTML through. It is three parts:

• <details> — the container. Everything between the tags is what collapses.
• <summary> — the always-visible label the reader clicks. Optional, but without one the browser shows a bare “Details” triangle.
• A blank line after </summary> — the part everyone forgets. See the next section.

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

Hidden content goes here, and it can use **Markdown**.

</details>

The Blank-Line Rule

This is the reason collapsible sections go wrong, and almost nothing that ranks for this topic says it out loud. In CommonMark, an HTML block runs until the first blank line. Everything before that blank line is copied to the output untouched — so if your content is pressed up against </summary>, it is still inside the raw HTML, and the parser never sees the asterisks as bold.

<details>
<summary>Click to expand</summary>
This line uses **Markdown**.
</details>

<details>
<summary>Click to expand</summary>
This line uses **Markdown**.
</details>

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

This line uses **Markdown**.

</details>

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

<p>This line uses <strong>Markdown</strong>.</p>
</details>

The blank line that matters is the one after </summary>. A blank line before </details> is optional in CommonMark and on GitHub, because a closing HTML tag can end a paragraph on its own. It is still worth adding: GitLab's documentation recommends it and it keeps the source readable.

Starting It Expanded

Add the open attribute to the opening tag. It is a boolean attribute — it takes no value — and the reader can still collapse the section afterwards.

<details open>
<summary>Already expanded</summary>

The reader can still collapse this one.

</details>

Accordion: One Section Open at a Time

Give several <details> blocks the same name and the browser treats them as a group: opening one closes the others. No JavaScript, and current versions of Chrome, Edge, Firefox, and Safari all support it. Try it in the preview.

<details name="faq">
<summary>What does it cost?</summary>

Nothing.

</details>

<details name="faq">
<summary>Does it work offline?</summary>

Yes.

</details>

What You Can Put Inside

Once the blank line has ended the HTML block, the content is ordinary Markdown. Headings, lists, tables, images, links, and fenced code blocks with syntax highlighting all behave exactly as they do outside the section.

<details>
<summary>Everything works in here</summary>

### A heading

A paragraph, a list, and a table:

- one
- two

| Column | Value |
| ------ | ----- |
| rows   | fine  |

</details>

<details>
<summary>Show the install command</summary>

```bash
npm install my-package
```

</details>

npm install my-package

Nesting Collapsible Sections

A <details> block can contain another one, as deep as you need. Each level needs its own blank lines around its body — the rule is per-block, not per-document. The usual shape is one outer toggle for a topic and an inner one per platform or per version.

<details>
<summary>Platform notes</summary>

<details>
<summary>macOS</summary>

Requires Xcode command line tools.

</details>

<details>
<summary>Windows</summary>

Requires the Visual C++ build tools.

</details>

</details>

Formatting the Summary Label

The <summary> line sits before the blank line, so it is still raw HTML — which means Markdown written inside it is not parsed. This surprises people who expect **Bold** to work there.

<details>
<summary>**Bold summary**</summary>

Body text.

</details>

<details>
<summary><b>Bold summary</b> with <code>code</code></summary>

Body text.

</details>

If you want a real Markdown heading as the label, the same blank-line rule that saved the body will save the summary: open the tag, leave a blank line, write the Markdown, leave another blank line, and close the tag. The blank line ends the HTML block long enough for the parser to process what is between.

<details>
<summary>

### A heading as the label

</summary>

Body text.

</details>

MDX is the exception: there, <summary>**Bold**</summary> on one line does render as bold, because MDX parses inline Markdown inside JSX tags.

Collapsible Sections Inside a List

Numbered setup instructions with an optional troubleshooting toggle per step is one of the most useful shapes there is, and it is where the indentation trap bites. Indent the block to the list item's content column — two spaces under a bullet, three under a 1. — and never four, which turns the whole thing into a code block.

1. Install the dependencies.

   <details>
   <summary>Troubleshooting</summary>

   Delete `node_modules` and try again.

   </details>

2. Run the build.

Native Alternatives

<details> is the answer on GitHub and GitLab because those are HTML-rendering surfaces. Several other tools grew their own collapsible syntax, and where one exists it is almost always the better choice — it is styled, it nests cleanly, and it does not depend on HTML being allowed.

Obsidian: foldable callouts

Add a - after the callout type to start it collapsed, or a + to start it expanded. Markdown, wikilinks, embeds, and nested callouts all work inside. That matters more in Obsidian than anywhere else: Obsidian never parses Markdown inside HTML, so a <details> body there can only hold plain text or HTML, with no blank lines.

> [!note]- Are callouts foldable?
> Yes. A minus sign collapses the callout by default.

> [!tip]+ This one starts open
> A plus sign expands it by default.

Material for MkDocs: ??? admonitions

Start an admonition with ??? instead of !!! and it renders as an expandable block. Requires the pymdownx.details extension in mkdocs.yml.

??? note "Collapsed by default"
    Requires the pymdownx.details extension.

???+ note "Expanded by default"
    The plus sign starts it open.

Hugo: the details shortcode

Hugo drops raw HTML unless you set markup.goldmark.renderer.unsafe = true, so a hand-written <details> block vanishes by default. Since v0.140.0 Hugo ships a built-in shortcode that emits the element for you, with summary, open, and name arguments.

{{< details summary="Show the install command" >}}
Run `npm install my-package`.
{{< /details >}}

Notion: toggle blocks

Notion drops pasted HTML, so <details> does nothing there. Its equivalent is a toggle block: type > followed by a space, or use /toggle. Note that this is the same keystroke that makes a blockquote in standard Markdown — in Notion a quote is " plus a space.

Chat apps: spoilers, and that is all

Discord, Slack, and Reddit allow no HTML in messages, so there is no collapsible section on any of them. The nearest thing is a spoiler, which hides a run of inline text behind a click but carries no label and no block content. Slack has no equivalent at all.

Discord:  Here is the answer: ||the butler did it||
Reddit:   Here is the answer: >!the butler did it!<

Common Mistakes

Four of these five are about where the blank lines and the indentation go. None of them produces an error message — the section just renders wrong, or swallows your document.

<details>
<summary>Notes</summary>
This is **bold**.
</details>

<details>
<summary>Notes</summary>

This is **bold**.

</details>

- Step one

    <details>
    <summary>More</summary>

    Hidden text.

    </details>

- Step one

  <details>
  <summary>More</summary>

  Hidden text.

  </details>

<details>
<summary>**Bold label**</summary>

Body.

</details>

<details>
<summary><b>Bold label</b></summary>

Body.

</details>

<details>
<summary>Notes</summary>

Hidden text.

## The rest of your document

<details>
<summary>Notes</summary>

Hidden text.

</details>

## The rest of your document

<details open>
<summary>Read me first</summary>

Important setup notes.

</details>

<details>
<summary>Read me first</summary>

Important setup notes.

</details>

Quick Reference

Platform Support

Support tracks one thing: whether the renderer allows raw HTML through. Document and repository platforms do. Chat apps do not, which is why there is no collapsible section in a Discord or Slack message and no workaround that produces one.

Frequently Asked Questions