Markdown collapsible sections

To make a collapsible section in Markdown, wrap the content in an HTML <details> element and put the clickable label in a <summary> element inside it. Markdown itself has no collapse syntax, so this relies on inline HTML, which GitHub, GitLab and many other renderers allow. Leave a blank line after </summary> so that Markdown inside the section is rendered instead of shown as plain text.

Markdown collapsible sections reference

Key facts

• Markdown has no native collapsible syntax. Collapsible sections use the HTML <details> and <summary> elements.
• GitHub documents this pattern in its guide to organizing information with collapsed sections.
• A blank line after </summary> is needed for Markdown inside the section to render, because in CommonMark an HTML block ends at a blank line.
• Add the open attribute, <details open>, to show the section expanded by default.
• Sections can be nested, and they can contain fenced code blocks, lists, tables and images.
• Renderers that strip raw HTML, including many chat apps and comment systems, show the tags as text or drop them.

Basic syntax

A collapsible section has two parts. The <details> element is the container, and the <summary> element is the label the reader clicks. Everything after the summary is hidden until the section is opened.

Markdown

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

This text is hidden until the reader opens the section.

</details>

Rendered output

HTML output

<details>
<summary>Click to expand</summary>
<p>This text is hidden until the reader opens the section.</p>
</details>

The browser draws the disclosure triangle and handles the click. No script is needed, which is why the pattern survives sanitizers that remove JavaScript.

Put the <summary> first inside <details>. If it is missing, the browser shows its own default label, which varies by browser and language.

The blank line rule for Markdown inside

This is the most common reason a collapsible section looks broken. In CommonMark and GitHub Flavored Markdown, a line that starts with <details> or <summary> begins a raw HTML block, and that block continues until the next blank line. Text inside the HTML block is passed through as-is, so Markdown syntax there is not processed.

Without a blank line: Markdown is not rendered

Markdown

<details>
<summary>Steps</summary>
- **Install** the app
- Open a file
</details>

Rendered output

HTML output

<details>
<summary>Steps</summary>
- **Install** the app
- Open a file
</details>

With a blank line: the list and bold render

Markdown

<details>
<summary>Steps</summary>

- **Install** the app
- Open a file

</details>

Rendered output

HTML output

<details>
<summary>Steps</summary>
<ul>
<li><strong>Install</strong> the app</li>
<li>Open a file</li>
</ul>
</details>

Both previews are shown open so the difference is visible. Put a blank line after </summary> and another before </details>.

GitLab states the same rule in its documentation: Markdown inside <details> works when you leave a blank line before and after the Markdown content.

Open by default

To show the section expanded when the page loads, add the open attribute. The reader can still click the summary to collapse it.

Markdown

<details open>
<summary>Release notes</summary>

This section starts expanded.

</details>

Rendered output

HTML output

<details open>
<summary>Release notes</summary>
<p>This section starts expanded.</p>
</details>

open is a Boolean attribute. Its presence is what matters, so open="false" still opens the section. To collapse it, remove the attribute entirely.

Code blocks and nested sections

Collapsible sections are often used to hide long logs, configuration files or sample output. A fenced code block works inside, as long as it is surrounded by blank lines.

Code block inside a collapsible section

Markdown

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

```text
Error: file not found
  at loadConfig (config.js:12)
```

</details>

Rendered output

Error: file not found
  at loadConfig (config.js:12)

HTML output

<details>
<summary>Full error log</summary>
<pre><code class="language-text">Error: file not found
  at loadConfig (config.js:12)
</code></pre>
</details>

Sections can also be nested. Place a complete <details> element inside another one, keeping the blank lines around any Markdown at each level.

Nested sections

Markdown

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

General notes go here.

<details>
<summary>macOS</summary>

macOS-specific notes.

</details>

</details>

Rendered output

HTML output

<details>
<summary>Platform notes</summary>
<p>General notes go here.</p>
<details>
<summary>macOS</summary>
<p>macOS-specific notes.</p>
</details>
</details>

Indenting the inner HTML by four or more spaces can turn it into an indented code block, so keep the tags at the start of the line.

Using it as a dropdown or spoiler

People searching for a Markdown dropdown, expand or spoiler usually want this same element. For a spoiler, make the summary describe what is hidden, for example <summary>Show answer</summary>. Formatting inside the summary itself, such as <strong> or <code>, is written as HTML, because the summary line is part of the raw HTML block.

• FAQ answers. One <details> per question, with the question as the summary.
• Long output. Logs, stack traces and generated files that most readers skip.
• Optional detail. Platform-specific steps or advanced options under a general instruction.
• Spoilers. Puzzle answers or plot details that the reader opts into.

Discord and some other chat apps have their own spoiler syntax that is unrelated to <details>. Check the documentation of the app you are writing for.

Flavor differences

Collapsible sections depend on whether a renderer passes raw HTML through and which tags its sanitizer keeps. The syntax is the same everywhere; support is not.

If the content must collapse in a tool that strips HTML, there is no Markdown fallback. Use a heading and keep the content visible, or link to a separate page. See inline HTML and Markdown flavors.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific allows the <details> and <summary> tags through its HTML sanitizer, so collapsible sections written this way display as clickable sections; leave a blank line after </summary> for Markdown inside, and check the preview. Try it in the Markdific online editor.

Common mistakes and gotchas

• No blank line after the summary. Without it, the Markdown inside is treated as raw HTML text, so lists and bold show as literal characters.
• Forgetting the closing tag. A missing </details> can swallow the rest of the document into the section.
• Writing Markdown in the summary. **bold** inside <summary> usually shows the asterisks. Use <strong> instead.
• Writing open="false". Any value of the open attribute opens the section. Remove the attribute to collapse it.
• Indenting the tags. Four or more leading spaces turn the HTML into an indented code block.
• Assuming every platform renders HTML. Chat apps and strict sanitizers often strip or escape it.

Best practices

• Write a summary that tells the reader what is inside, such as "Full error log (40 lines)".
• Always put a blank line after </summary> and before </details>.
• Keep essential instructions visible. Collapse optional or long material only.
• Avoid deep nesting. One or two levels are easier to scan.
• Preview the document on the platform where it will be published, since HTML support varies.

HTML equivalent

Collapsible sections are already HTML. The Markdown processor converts only the Markdown inside the section and leaves the <details> and <summary> tags as they are.

Markdown

<details>
<summary>More</summary>

Some *emphasized* text.

</details>

HTML output

<details>
<summary>More</summary>
<p>Some <em>emphasized</em> text.</p>
</details>

FAQ

How do you make a collapsible section in Markdown? Wrap the content in <details> and put the label in <summary>, with a blank line after </summary>. Markdown has no native collapse syntax, so this uses inline HTML.

Does GitHub support collapsible sections? Yes. GitHub documents the <details> and <summary> pattern in its writing guide, including the open attribute.

Why is Markdown not rendering inside my details tag? There is probably no blank line after </summary>. Without it, the content is part of a raw HTML block and is not processed as Markdown.

How do I make a collapsible section open by default? Add the open attribute to the opening tag: <details open>. Remove the attribute to start collapsed.

Can I put a code block inside a collapsible section? Yes. Put a fenced code block inside <details> with a blank line before and after it.

Can collapsible sections be nested? Yes. Place a complete <details> element inside another one, keeping blank lines around the Markdown at each level.

Does Obsidian support details and summary? Obsidian sanitizes HTML, and its help states that it does not render Markdown inside HTML elements. For collapsible Markdown content in Obsidian, use a foldable callout such as > [!note]-. See alerts and callouts.

Sources and compatibility references

• GitHub Docs: Organizing information with collapsed sections
• GitLab Docs: GitLab Flavored Markdown (collapsible section)
• CommonMark Spec 0.31.2: HTML blocks
• MDN: The details disclosure element
• Visual Studio Code: Markdown and Visual Studio Code
• Obsidian Help: HTML content

Use these primary references for syntax rules. Renderer behavior can still vary by version and configuration, so preview important documents in their final destination.

To see how your Markdown renders while you write, open the file in Markdific, a Markdown viewer and editor for Mac, Windows and Linux.

Related pages

• Markdown documentation hub
• Inline HTML
• Alerts and callouts
• Fenced code blocks
• Blockquotes
• Markdown flavors
• Markdown cheat sheet