Can I use Markdown inside a details section?

GitHub supports Markdown content inside the details element. Add a blank line after the summary before paragraphs, lists, or fenced code blocks.

How do I make the section open by default?

Add the open attribute to the opening tag, as in . The reader can still collapse the section.

Can I customize the dropdown arrow?

The browser and GitHub stylesheet control the standard disclosure marker. Avoid relying on custom styling unless you control the publishing environment.

Why does the content render incorrectly elsewhere?

The pattern uses embedded HTML, and Markdown processors differ in HTML support. Check the destination renderer before copying the document.

Collapsible Sections in GitHub Markdown

Create a collapsible section in GitHub Markdown with the HTML details and summary elements. Put the visible label inside summary, then place Markdown content after the closing summary tag and before the closing details tag. Use <details> on one line, <summary>Visible label</summary> on the next line, and </details> after the hidden content. Add the open attribute to details when the section should start expanded. GitHub supports this pattern in many Markdown contexts, but other renderers may handle embedded HTML differently. Keep essential instructions visible outside the collapsed area.

The details and summary pattern

The details element creates the expandable container. The summary element supplies the text that readers click. A minimal structure has an opening details tag, a summary line, the hidden content, and a closing details tag. The summary should describe the content precisely, such as Installation notes or Troubleshooting a token error. Markdown inside the details element can include paragraphs, lists, links, and code blocks. Leave a blank line after the summary when the section contains Markdown. This helps GitHub parse the content as a separate block. Use the open attribute when readers should see the content immediately. Without that attribute, the section starts collapsed. Avoid nesting several details sections unless each summary remains easy to identify.

Choose content that benefits from collapsing

Collapsible sections work well for optional setup, long command output, platform-specific instructions, troubleshooting explanations, and reference material. They reduce visual length without removing information from the page. Do not hide a required first step, a security warning, or a decision that most readers must make. A reader may never open the section, and some tools may not expose the control clearly. Write a useful summary instead of using labels such as More or Click here. Include the expected audience in the label when possible. For example, Windows setup details tells readers why the section exists. Keep command examples complete inside the section, including prerequisites and expected results.

Rendering, accessibility, and maintenance

GitHub renders these elements as native expandable content in supported Markdown surfaces. The exact appearance comes from the page stylesheet, so do not depend on a particular border, icon, or color. The summary text should make sense without surrounding visual cues. Check keyboard operation and focus behavior on the published page, especially when a section contains forms or custom HTML. Embedded HTML may be sanitized or rendered differently outside GitHub. If documentation is copied to a package registry, static site, or internal tool, test the copied version. Keep the closing details tag in place and update the hidden content when commands change. A broken tag can cause later content to render unexpectedly.

How do you do it step by step?

1Choose optional or supporting content that readers may not need on their first visit.
2Add an opening <details> tag and write a precise <summary> label for the expandable section.
3Insert a blank line, then add the Markdown, commands, links, or explanation to hide.
4Close the section with </details> and add open if the content should start expanded.
5Preview the page on GitHub and test the section with keyboard navigation and a narrow screen.

Working example

This example hides platform-specific installation notes while keeping the main setup path short.

Input

<details>
<summary>Show Linux package installation</summary>

Install the required package before running the project:

```bash
sudo apt install libexample-dev
```

</details>

Result

GitHub shows a clickable summary labeled Show Linux package installation. The paragraph and command appear after the reader expands the section.

Keep a required dependency in the main instructions if users on that platform cannot continue without it.

Frequently asked questions

Can I use Markdown inside a details section?: GitHub supports Markdown content inside the details element. Add a blank line after the summary before paragraphs, lists, or fenced code blocks.
How do I make the section open by default?: Add the open attribute to the opening tag, as in <details open>. The reader can still collapse the section.
Can I customize the dropdown arrow?: The browser and GitHub stylesheet control the standard disclosure marker. Avoid relying on custom styling unless you control the publishing environment.
Why does the content render incorrectly elsewhere?: The pattern uses embedded HTML, and Markdown processors differ in HTML support. Check the destination renderer before copying the document.