How to make a collapsible section in Markdown:the details and summary tags.

The syntax

A collapsible section is a plain HTML element: <details> is the container, <summary> is the clickable line, and everything after the summary is hidden until the reader clicks. The browser (or the Markdown app's web view) does the opening and closing, so there is no script and no extra syntax to learn.

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

Hidden text goes here.

</details>

Closed, the reader sees a small triangle and the words Click to expand. Clicking turns the triangle and shows the text. The same pattern is what GitHub READMEs, issues and pull request comments use for long logs and optional notes.

The blank line rule

Markdown inside a <details> block is only processed if it is separated from the HTML tags by a blank line. This is how CommonMark reads an HTML block: it runs to the next blank line and is passed through as raw HTML. Without the blank line, your **bold** and your list stay as literal characters.

<details>
<summary>Broken</summary>
- this list is not turned into a list
</details>

<details>
<summary>Works</summary>

- this one is a list

</details>

Put a blank line after </summary> and another one before </details>. The summary line itself is HTML too, so use <b>bold</b> or <code>code</code> there, not Markdown.

Open by default

Add the open attribute to start with the section expanded. The reader can still collapse it.

<details open>
<summary>Prerequisites</summary>

Node 20 or later.

</details>

Use it sparingly: a page where everything starts open has no reason to be collapsible, and a page where everything starts closed hides the useful parts. A good rule is to keep the answer visible and fold away the evidence, such as long output, a full config or a list of edge cases.

Examples: code, nesting and a long list

A code block inside a section needs its blank lines like any other Markdown:

<details>
<summary>Full config</summary>

```json
{ "retries": 3, "timeout": 30 }
```

</details>

Sections can be nested. Indent the inner one if you like, but the blank lines are what matter:

<details>
<summary>Troubleshooting</summary>

<details>
<summary>The app does not start</summary>

Check the log in the console.

</details>

</details>

Here is a section as a reader sees it, closed until you click:

Show the full log

Everything here is hidden until the title is clicked.

When to use a collapsible section

Folding is worth it when the reader can finish the task without opening the section. Good candidates are long command output, a full configuration file, a table of options, a changelog of old versions, or a list of troubleshooting steps for rare problems. A short note that most readers need should stay in plain view.

A section is also a tidy way to put long pasted logs into a bug report or a pull request description: the reader sees the summary of what went wrong first and opens the log only if they need it. Give the summary a specific title, such as Build log (412 lines), so the reader knows what is inside before clicking.

Common mistakes

• No blank line. The text inside shows raw Markdown. Add a blank line after the summary and before the closing tag.
• Markdown in the summary. Use HTML tags there.
• A missing closing tag. Everything below stays inside the section.
• An app that strips HTML. Some renderers remove tags they do not trust, and then the text is simply visible. If the section must work everywhere, test it where it will be read.
• Headings inside the summary. The heading does not appear in the outline of most apps. Put the heading above the section instead.

Collapsed text is still in the file, so search and diffs see it, but a reader who never clicks will not. Do not hide anything essential, such as a warning.

Seeing it work

To check a section, open the file in a reader that renders HTML. DotMD shows <details> as a section that opens on click, with Markdown inside it formatted, and in DotMD Editor Insert → Collapsible Section writes the tags for you. Reading is free.

Questions about collapsible sections in Markdown

More questions