Markdown Collapsible Section
How to create collapsible expandable sections in markdown using HTML details and summary tags. Common in GitHub READMEs.
What is markdown collapsible section?
Collapsible sections in markdown use the HTML <details> and <summary> elements. The <summary> text is always visible and acts as the toggle — clicking it expands or collapses the hidden content inside <details>. This is widely supported on GitHub and GitLab for hiding long code samples, changelogs, or optional content.
Syntax
Basic collapsible
Note the blank line after <summary> — it allows markdown to be parsed inside the block.
Click to expand
Hidden content here.With code block inside
Collapsible sections can contain any markdown including code blocks.
See the full code
(code block)Platform support
| Platform | Supported | Notes |
|---|---|---|
| GitHub | Yes | Fully supported in README and issues |
| GitLab | Yes | — |
| Obsidian | Yes | — |
| Discord | No | — |
| Notion | No | — |
| Slack | No | — |
Common mistakes
No blank line after </summary>
Always add a blank line after </summary> and before </details>
Without blank lines, markdown inside the details block is not parsed. The blank line signals to the parser that what follows is block-level markdown.
Tips for collapsible section
Put verbose content (full changelogs, Windows-specific instructions, advanced configuration) inside collapsible sections to keep READMEs readable.
Add the open attribute to make the section expanded by default: <details open>.
Frequently asked questions
Everything you need to know.
How do I make a collapsible section in a GitHub README?
Use <details><summary>Title</summary> content </details>. Add a blank line after </summary> so markdown is parsed inside.
Related elements
HTML Block
Most markdown parsers allow you to embed raw HTML directly in your markdown file. HTML blocks let you use elements not supported by markdown — custom divs, details/summary, colored text, form elements, and more. HTML support depends on the platform — some sanitize or strip it entirely.
Code Block
Markdown supports two types of code formatting: inline code with single backticks (`) for short snippets, and fenced code blocks with triple backticks (```) for multi-line code with optional syntax highlighting.
Alert / Callout
Alerts (also called callouts or admonitions) are styled blockquotes that highlight important information with color and an icon. GitHub introduced a > [!NOTE] syntax in 2023. Obsidian uses > [!tip] syntax. Both extend standard blockquote syntax with a type keyword on the first line.
Try it in the editor
Paste your markdown and see collapsible section rendered instantly with professional themes.