Markdown Collapsible Section: details, Dropdown and Toggle (2026)

TL;DR: A Markdown collapsible section is the HTML <details> element with a <summary> label inside it. The one rule that trips everyone up: leave a blank line between </summary> and your Markdown content, or the Markdown renders as literal text. That is not a GitHub quirk — it is the CommonMark HTML-block boundary, so it applies in every conformant renderer.

A Markdown collapsible section hides a block of content behind a clickable label, and you write it with two HTML tags rather than any Markdown syntax. It works on GitHub, GitLab, Docusaurus, Typora, Jupyter and most local viewers — including MacMD Viewer, which renders <details> in both the app window and the QuickLook preview. It does not work on Bitbucket Cloud, which strips arbitrary HTML, nor in Slack messages, whose mrkdwn has no HTML layer at all.

Here is the whole thing:

<details>
<summary>Click to expand</summary>
 
Your **Markdown** content goes here.
 
</details>

This guide covers the syntax, the blank-line rule and why it exists, dropdowns and accordions, the native toggle equivalents in Notion, Obsidian and MkDocs, the difference between a collapsible section and a spoiler, and the mistakes that break rendering silently.

What Is a Markdown Collapsible Section?

There is no collapsible syntax in Markdown itself. Every collapsible section in a .md file is the HTML <details> element, which MDN describes as a disclosure widget "in which information is visible only when the widget is toggled into an open state." Markdown renderers pass it through untouched — which is exactly why support varies so much by platform.

That single fact explains most of the confusion around this feature. A platform that renders raw HTML gives you collapsible sections for free. A platform that sanitizes HTML gives you nothing, and no amount of syntax tweaking will change that. It is the same situation as Markdown comments, which are also an HTML feature borrowed into Markdown rather than a Markdown feature.

Markdown details syntax: what each tag does

Two elements, one nesting rule:

• <details> is the container and the widget. Its permitted content is one <summary> element followed by flow content. Its implicit ARIA role is group.
• <summary> is the clickable label. It may only be used as the first child of <details>. If the first child is something else, the browser substitutes a default label — typically the word "Details".

The disclosure triangle you see next to the label is not decoration you add. Standards-compliant browsers apply display: list-item to <summary>, and the triangle is that list marker.

How Do You Create a Markdown Collapsible Section?

Four steps: open a <details> tag, put the label in <summary>, leave a blank line, write your Markdown. The blank line is the only step people get wrong, and it fails silently — no error, just asterisks where bold text should be.

Step 1: Wrap the content in <details>

<details>
Everything in here collapses.
</details>

With no <summary>, this still works — the browser labels it "Details" and folds the content. It is rarely what you want, but it shows that <details> alone is the widget.

Step 2: Label it with <summary>

The <summary> must be the first child. Anything else and you lose your label:

<details>
<summary>Installation instructions</summary>
</details>

Step 3: Leave a blank line before your Markdown

<details>
<summary>Installation instructions</summary>
 
Run `npm install`, then **restart the dev server**.
 
- [ ] Clone the repo
- [ ] Install dependencies
 
</details>

That blank line after </summary> is what lets the bold text, the inline code and the Markdown checkboxes render as Markdown instead of literal characters. The next section explains why.

Step 4: Open it by default with the open attribute

<details open>
<summary>Read this first</summary>
 
Visible as soon as the page loads.
 
</details>

open is a Boolean attribute: the section is expanded when the attribute is present and collapsed when it is absent. Writing open="false" does not collapse it — the attribute is still there, so the section still renders open. Delete the attribute instead.

Why the Blank Line After </summary> Is Required

Because CommonMark says so, not because GitHub is being difficult. The CommonMark specification lists details among the block-level tag names that open a type 6 HTML block, and the end condition for that block type is verbatim: "line is followed by a blank line." Until that blank line arrives, the parser is still inside a raw HTML block and treats everything as HTML — so **bold** is just four asterisks and some letters.

Side by side:

<details>
<summary>Broken</summary>
**this stays literally asterisked**
</details>
 
<details>
<summary>Works</summary>
 
**this renders bold**
 
</details>

Once the blank line closes the HTML block, normal Markdown parsing resumes and everything after it is interpreted as CommonMark — emphasis, lists, code fences, tables, all of it.

The practical consequence is that this behaviour is portable. It is not a GitHub rendering bug you can hope to see fixed; any CommonMark-conformant renderer will behave the same way. Worth knowing, because GitHub's own collapsed sections documentation demonstrates the blank lines in its example without ever mentioning the requirement in prose. GitLab's docs are more forthcoming: "Remember to leave a blank line before and after any Markdown sections."

GitHub's canonical example also puts a blank line after <details> itself, which is a reasonable habit — it makes the block boundary obvious to anyone editing the file later.

How Do You Make a Markdown Dropdown?

A Markdown dropdown is the same <details> element under a different name. There is no separate dropdown syntax, and searching for one is how most people end up here. What changes is what you put inside it.

A dropdown reads best when the summary is a question or a category and the body is long enough to be worth hiding:

<details>
<summary>Why did the build fail?</summary>
 
The Node version in CI was pinned to 18. The `engines` field requires 20.
 
```bash
nvm use 20 && npm ci
```
 
</details>

Code fences work inside a collapsible block, which makes this the standard way to attach a 200-line stack trace to a bug report without burying the report. It is also why <details> shows up so often in README files — FAQ blocks, per-platform install instructions and screenshot galleries all collapse well.

How Do You Build a Markdown Accordion?

Give several <details> elements the same name attribute. The browser then keeps only one of them open at a time, which is the accordion behaviour, with no scripting involved:

<details name="faq">
<summary>Does it work offline?</summary>
 
Yes.
 
</details>
 
<details name="faq">
<summary>Is there a trial?</summary>
 
No.
 
</details>

Two details from the spec worth knowing. Grouped elements do not have to be adjacent in the source — the name attribute is what binds them, not their position. And if several elements in the group carry open, only the first one in source order actually renders open.

How Do You Make a Markdown Toggle in Notion, Obsidian and MkDocs?

Several ecosystems have their own toggle syntax that is shorter than HTML and better integrated than a raw <details> block. If you are writing for one of these tools specifically, use the native form.

A mnemonic for the two plus/minus systems, because they agree with each other: plus always means already expanded. Obsidian's - collapses and + expands; MkDocs Material's ??? is collapsed and ???+ is expanded.

That Python-Markdown row is the one clean escape from the blank-line dance. With the md_in_html extension, markdown="1" applies that tag's default parsing mode — block-level in the case of <details> — and the Markdown inside then renders with no blank line at all. markdown="block" forces block parsing explicitly, markdown="span" restricts it to inline syntax such as links and emphasis.

For Obsidian specifically, reach for the foldable callout rather than raw HTML — it is the documented, supported path, and it inherits your theme's styling.

Is a Markdown Spoiler the Same as a Collapsible Section?

No, and the distinction matters if you are writing for a chat platform. A Markdown spoiler masks inline text until the reader clicks it. A collapsible section folds an entire block of content behind a label. Different mechanisms, different platforms.

Reddit uses >!spoiler text!< and Discord uses a pair of pipes on each side of the text:

Reddit:   >!the butler did it!<
Discord:  ||the butler did it||

Neither platform supports <details>, and neither spoiler syntax gives you a foldable block with a custom label. If what you actually want is a collapsible section on Reddit or Discord, the honest answer is that it does not exist there.

Which Platforms Support Collapsible Markdown?

The <details> element itself has 96.68% global browser support as of July 2026, according to caniuse — Chrome 12+, Edge 79+, Safari 6+, Firefox 49+, Opera 15+ and iOS Safari 6+, with Internet Explorer and Opera Mini as the only holdouts. So when a collapsible section fails, the browser is almost never the reason. The renderer is.

What Are the Common Collapsible Markdown Mistakes?

Five failure modes account for nearly everything. Four of them are silent — you get plain text or a section that will not collapse, with no warning anywhere.

Missing the blank line after </summary>

The one covered above. Symptom: your bold, links and lists appear as literal characters inside an otherwise working collapsible block.

Writing open="false"

It renders open. open is Boolean — its presence is the signal, its value is ignored. Remove the attribute to collapse the section.

Putting <summary> somewhere other than first

<summary> may only be the first child of <details>. Put a paragraph above it and the browser falls back to its default label, so your carefully worded summary text ends up inside the body instead of on the toggle.

Assuming every platform renders it

If you paste a <details> block into a Bitbucket Cloud pull request or a Slack message, you get raw tags or stripped text. Check the matrix above before writing documentation that has to render in more than one place.

Expecting it to survive export

Pandoc passes <details> through to HTML-family outputs and discards it for PDF and DOCX. Collapsible content does not survive a conversion to a paginated format — there is nothing to click in a PDF. Plan for the content to be either always visible or absent.

Are Collapsible Sections Accessible?

Mostly yes, and the best thing you can do is leave them alone. <summary> is focusable with Tab and toggles with Enter or Space, and the browser manages aria-expanded for you — the guidance is to add no manual ARIA at all, since native <details> beats a hand-rolled disclosure widget.

One caveat worth respecting: MDN notes that the role browsers assign to <summary> varies, and some assign a default button role, "which removes all roles from its children." A heading inside <summary> may therefore not be exposed as a heading, so do not rely on it for document structure. On find-in-page, text inside a collapsed <details> was historically invisible to Ctrl+F; modern browsers can auto-expand a collapsed section when in-page search matches its content. The one real limitation is animation — there is no built-in transition between the open and closed states, so any easing has to be applied yourself via the details[open] selector.

How Do You Preview Collapsible Sections on Mac?

macOS has no built-in Markdown renderer, so a .md file full of <details> blocks opens in TextEdit as raw tags. You need something that renders HTML inside Markdown.

MacMD Viewer renders <details> and <summary> in both the app window and the QuickLook preview, so pressing Space on a README in Finder gives you a working collapsible section without opening anything. It also live-reloads on save, which is the fastest way to check that your blank lines are in the right place while you are editing. Download MacMD Viewer — $19.99, one-time.

VS Code and Cursor render <details> in their built-in preview panes as well — both run Markdown through markdown-it with raw HTML enabled — so they are the obvious alternative if the file is already open in your editor. For a wider comparison of local viewers, see the best Markdown viewer roundup.

Frequently Asked Questions

How do you create a collapsible section in Markdown?

Wrap the content in HTML <details> tags, put the clickable label in a <summary> tag as the first child, and leave one blank line between </summary> and your Markdown content. There is no Markdown syntax for this — <details> is an HTML element that Markdown passes through to the output.

Why does my Markdown not render inside a collapsible section?

You are missing the blank line after </summary>. CommonMark treats <details> as a type 6 HTML block, and the spec's end condition for that block is verbatim "line is followed by a blank line." Until that blank line appears, everything is raw HTML, so **bold** stays literally asterisked.

How do you make a Markdown collapsible section open by default?

Add the open attribute to the opening tag: <details open>. It is a Boolean attribute, so writing open="false" still renders the section open — the only way to collapse it is to remove the attribute entirely.

Is there a native Markdown syntax for collapsible sections?

No. Neither CommonMark nor GitHub Flavored Markdown defines one. Every collapsible section in a .md file is the HTML <details> element passed through by the renderer, which is why platforms with no raw-HTML rendering — Bitbucket Cloud strips it, Slack never had it — have no collapsible sections at all.

What is the difference between a Markdown dropdown, toggle and spoiler?

Dropdown and toggle are informal names for the same <details> disclosure widget, or for a platform's native equivalent such as a Notion toggle block. A spoiler is a different mechanism: Reddit's >!text!< and Discord's double-pipe syntax mask inline text until you click it, they do not fold a block of content.

Can you make an accordion where only one section is open at a time?

Yes, with no JavaScript. Give several <details> elements the same name attribute and the browser keeps only one open at a time. The grouped elements do not have to be adjacent in the source, and if several of them carry open, only the first one in source order renders open.

Which platforms do not support collapsible Markdown?

Bitbucket Cloud strips arbitrary HTML from Markdown, so <details> never renders. Slack's mrkdwn supports only bold, italic, strikethrough, code, quotes, lists and links — no HTML and no collapsible. Pandoc passes <details> through to HTML output but discards it for PDF and DOCX.