Collapsible Sections in GitHub Markdown (details & summary)

When reporting bugs or documenting complex features in GitHub Issues and Pull Requests, it is common to encounter long stack traces, 500-line JSON payloads, or lengthy log files. Pasting these directly into the issue description makes the thread unreadable and forces maintainers to scroll endlessly.

The solution is to hide this supplementary context inside a native HTML collapsible section.

This tutorial explains the exact syntax required by GitHub’s markdown parser, the common formatting pitfalls that break code blocks, and how to automate the process securely.

The Standard GitHub Collapsible Syntax

GitHub Flavored Markdown (GFM) natively supports the HTML <details> and <summary> elements. This allows you to create interactive UI accordions without any JavaScript. As documented in GitHub Docs: collapsed sections, GitHub issues, PRs, discussions, READMEs and wikis render details and summary tags. Other markdown renderers may differ, so check your platform before using.

Here is the exact syntax required to create a collapsible block:

<details>
<summary>Click here to view the full stack trace</summary>

```bash
Error: ENOSPC: System limit for number of file watchers reached, watch '/app/node_modules'
    at FSWatcher.<computed> (node:internal/fs/watchers:244:19)
    at Object.watch (node:fs:2313:34)
```

</details>

When rendered on GitHub, the user sees a single clickable line: “Click here to view the full stack trace”. Clicking it expands the block to reveal the bash snippet.

The “Blank Line” Parsing Trap

The most common mistake developers make is forgetting the blank line between the <summary> tag and the content.

If you write this:

<details>
<summary>My Logs</summary>
```json
{ "status": 500 }
```
</details>

The markdown parser will fail. The triple backticks will be rendered as literal text, and your code block will lose all syntax highlighting and formatting.

GitHub’s Markdown parser follows CommonMark: an HTML block continues until the next blank line, so Markdown written directly after the summary line is treated as raw HTML and shown literally. A blank line after the summary line ends the HTML block; a blank line before the closing details tag is not required.

How to Handle Long Logs: Trade-Off Analysis

When faced with attaching long logs to a GitHub Issue, developers generally choose between three methods. Here is how they compare:

GitHub rejects issue and comment bodies longer than 65,536 characters with the error ‘Body is too long (maximum is 65536 characters)’ — an undocumented limit visible in real projects such as golang/go#45998.

For maximum visibility and minimal friction for maintainers, the <details> Block is the superior choice for logs that fit within the body limit, provided it is formatted correctly.

Formatting the Summary Line

Markdown inside the summary tag is NOT rendered (Bold shows literally); use HTML instead, e.g. <b>Bold</b> or <code>…</code>.

<details>
<summary><b>Build log</b> (2,000 lines)</summary>

```bash
# ...
```

</details>

Advanced Usage

Default Open State

If you want the section to be expanded by default when the page loads, you can add the open attribute to the <details> tag:

<details open>
<summary>Important Prerequisites (Expanded by Default)</summary>

1. Ensure you are on Node v20+
2. Run `pnpm install`

</details>

Nesting Collapsible Sections

You can nest details tags to create a hierarchy of logs, which is extremely useful for mono-repo builds where multiple packages fail independently:

<details>
<summary>Build Failures (3 Packages)</summary>

<details>
<summary>@utiliome/core</summary>

```typescript
Type error: Cannot find module 'lodash'
```

</details>

<details>
<summary>@utiliome/web</summary>

```bash
vite build failed with exit code 1
```

</details>

</details>

Automating Collapsible Markdown Generation

Writing HTML tags manually and remembering the blank line rules while context-switching between the terminal and the browser is error-prone.

Instead of formatting HTML by hand, you can use the Markdown Collapsible Section Generator. It outputs correctly formatted details and summary blocks with the required blank line, accepts uploaded markdown files, and provides a preview.

It operates entirely in your browser without uploading your text to a server, ensuring your data remains private.