Markdown Collapsible Content Tutorial

Markdown has no native collapsible syntax. But nearly all mainstream Markdown renderers support inline HTML, so we can use the HTML5 <details> and <summary> tags to create collapsible content sections. This approach is widely used and reliable on platforms like GitHub READMEs, GitLab Wikis, and Obsidian.

Basic Syntax: <details> + <summary>

<details> is a native HTML5 element that creates a collapsible widget. <summary> is its child element, displayed as a clickable header bar. Clicking it toggles the visibility of the remaining content inside <details>.

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

  This content is hidden by default. It becomes visible after expanding.

</details>

Rendered result: click the "Click to expand details" header bar, and the content below appears; click again to collapse it.

Key Points

• <details> is the outer container that defines the collapsible region
• <summary> is the clickable title text, always visible
• Everything after <summary> and before </details> is hidden by default
• You must leave a blank line after the <summary> tag — otherwise Markdown formatting inside (headings, lists, code blocks, etc.) won't render correctly

Default Open State

Add the open attribute to the <details> tag, and the collapsible section will be expanded by default when the page loads:

<details open>
  <summary>This content is expanded by default</summary>

  You can see this text immediately on page load.
  Click the header bar to collapse it.

</details>

open is a boolean attribute — simply including it enables the behavior, no value needed. This is useful for FAQ pages or any scenario where content should be "shown first, then collapsible."

Using Markdown Formatting Inside Collapsible Sections

You can use standard Markdown syntax inside collapsible sections, with one requirement: you must leave a blank line after the <summary> tag. This blank line tells the Markdown renderer to "start parsing Markdown formatting from here."

<details>
  <summary><b>Installation Steps</b></summary>

  ## Prerequisites

  - Node.js 18 or higher
  - Git

  ## Install Commands

  ```bash
  git clone https://github.com/example/repo.git
  cd repo
  npm install

Supported Markdown formatting includes:

| Format | Supported | Example |
|--------|-----------|---------|
| Headings `##` | Yes | `## Subheading` |
| Lists `-` | Yes | `- List item` |
| Bold `**` | Yes | `**Bold text**` |
| Code blocks `` ``` `` | Yes | Triple backtick fencing |
| Images `![]()` | Yes | `![Screenshot](url)` |
| Links `[]()` | Yes | `[Docs](url)` |
| Tables | Yes | Standard table syntax |
| Task lists `- [ ]` | Yes | GitHub-style task lists |

If Markdown inside a collapsible section isn't rendering (showing raw text instead), 99% of the time it's because you forgot the blank line after `<summary>`.

## Nested Collapsible Sections

`<details>` tags support nesting — you can place one collapsible section inside another:

```markdown
<details>
  <summary>Chapter 1: Getting Started</summary>

  This is an overview of Chapter 1.

  <details>
    <summary>1.1 Environment Setup</summary>

    Node.js installation steps...

  </details>

  <details>
    <summary>1.2 Your First Project</summary>

    Detailed steps for creating a project...

  </details>

</details>

Nested collapsibles are especially useful in technical documentation — fold large chapters, then fold sub-chapters within each one. Readers can expand only the sections they care about without scrolling through a long document.

A word of caution: limit nesting to 3 levels. Deeper nesting makes indentation excessive, code harder to maintain, and navigation cumbersome for readers.

Formatting Inside <summary>

You can use HTML formatting inside the <summary> tag to enhance the header display:

<!-- Bold header -->
<details>
  <summary><b>Important Notice</b></summary>
  Content...
</details>

<!-- Header with icon -->
<details>
  <summary>💡 Quick Tip</summary>
  Content...
</details>

<!-- Header with code -->
<details>
  <summary><code>npm install</code> Instructions</summary>
  Content...
</details>

Pure Markdown formatting (like **bold**) inside <summary> isn't consistently supported across all renderers, so use HTML tags (<b>, <code>, etc.) to format summary text instead.

Practical Use Cases

Collapsible content shines in these scenarios:

Detailed Instructions in READMEs

## Quick Start

Install with a single command: `npm install my-lib`

<details>
  <summary>Full Installation Options</summary>

  | Flag | Description | Default |
  |------|-------------|---------|
  | `--global` | Install globally | false |
  | `--save-dev` | Save as dev dependency | false |
  | `--registry` | Specify registry | npm official |

</details>

FAQ Sections

## Frequently Asked Questions

<details>
  <summary>How do I reset my password?</summary>

  1. Click "Forgot password" on the login page
  2. Enter your registered email
  3. Check your inbox for the reset email
  4. Click the link in the email to set a new password

</details>

<details>
  <summary>What payment methods are supported?</summary>

  Currently supported: Credit Card, PayPal, Bank Transfer.

</details>

Long Code and Logs

<details>
  <summary>View full log output</summary>

  ```log
  2024-01-15 10:00:01 [INFO] Server started on port 3000
  2024-01-15 10:00:02 [INFO] Database connected
  2024-01-15 10:00:03 [WARN] Cache miss for key: user_settings
  ... (hundreds of log lines)

### Changelog

```markdown
## Changelog

<details>
  <summary>v2.0.0 (2024-01-15)</summary>

  ### New Features
  - Added dark mode
  - Multi-language support

  ### Bug Fixes
  - Fixed login page flickering

</details>

<details>
  <summary>v1.9.0 (2024-01-01)</summary>

  ### New Features
  - Added export functionality

</details>

Platform Compatibility

<details> / <summary> are standard HTML5 elements and work reliably on Markdown renderers that support inline HTML:

GitHub Specifics

GitHub is the platform where <details> + <summary> in Markdown is most widely used. The GitHub Docs has a dedicated page on this technique, calling them "collapsed sections." They work in GitHub README.md files, Issue comments, Pull Request descriptions, and GitHub Wikis.

Hugo Static Sites

Hugo's default Goldmark renderer strips raw HTML. To make <details> tags work, enable unsafe rendering in your config:

[markup.goldmark.renderer]
unsafe = true

Alternatively, use a Hugo shortcode to wrap <details>:

<!-- layouts/shortcodes/details.html -->
<details{{ with .Get "open" }} open{{ end }}>
  <summary>{{ .Get "title" }}</summary>
  {{ .Inner | markdownify }}
</details>

Then in your Markdown:

{{</* details title="Click to expand" */>}}

Hidden content

{{</* /details */>}}

Custom Styling

In environments that support custom CSS (Obsidian, Typora, static sites), you can style <details> elements:

<details style="border: 1px solid #ddd; border-radius: 4px; padding: 8px;">
  <summary><b>Styled collapsible section</b></summary>

  This collapsible section has a border and rounded corners.

</details>

Or set styles globally in CSS:

details {
  border: 1px solid #e0e0e0;
  border-radius: 6px;
  padding: 12px;
  margin: 16px 0;
  background: #fafafa;
}

details summary {
  cursor: pointer;
  font-weight: bold;
  color: #333;
}

details summary:hover {
  color: #0066cc;
}

Note: GitHub strips style attributes, so custom styling doesn't work on GitHub.

Frequently Asked Questions

Does Markdown have a native collapsible syntax?

No. Markdown's design philosophy focuses on content structure, not interactive features. Collapsible content is an interactive behavior that requires HTML.

Why isn't Markdown rendering inside my collapsible section?

The most common cause is a missing blank line after the <summary> tag. There must be an empty line between <summary>...</summary> and the actual content for the Markdown renderer to parse formatting correctly.

Can I use collapsible sections on GitHub?

Absolutely. GitHub officially recommends using <details> and <summary> tags for collapsible sections. They work in READMEs, Issues, and PR descriptions. However, GitHub doesn't support custom styling (the style attribute gets stripped).

Can I nest collapsible sections indefinitely?

Technically yes, but limiting nesting to 3 levels is recommended. Excessive nesting leads to deep indentation, harder-to-maintain code, and poor usability. One or two levels is sufficient for most use cases.

Are <details> and <summary> standard HTML?

Yes. They are standard elements in the HTML5 specification, supported by all modern browsers. The MDN documentation provides complete specifications for the details element and summary element.

References

• GitHub Docs - Organizing information with collapsed sections
• MDN - HTML details element
• HTML Standard - The details element