> Content index: https://devbio.me/blogs/llms.txt > Canonical page: https://devbio.me/blogs/markdown-collapsible-section --- title: Markdown Collapsible Section: The Blank Line Rule description: A Markdown collapsible section is HTML, not Markdown. One blank line after the summary tag decides whether your bold and lists render or not. keywords: markdown collapsible section, collapsible section, collapsible markdown, markdown dropdown published: 2026-09-23 updated: 2026-09-25 url: https://devbio.me/blogs/markdown-collapsible-section word_count: 1998 --- # Markdown Collapsible Section: The Blank Line Rule > A Markdown collapsible section is HTML, not Markdown. One blank line after the summary tag decides whether your bold and lists render or not. Canonical: https://devbio.me/blogs/markdown-collapsible-section Published: 2026-09-23 ## Related Pages - [Markdown Center Text: What Works, What Gets Stripped](https://devbio.me/blogs/markdown-center-text) - [Markdown Underline: Why u Fails on GitHub (Use ins)](https://devbio.me/blogs/underline-in-markdown) - [Markdown Comment: Why Yours Shows Up on the Page](https://devbio.me/blogs/markdown-comment-syntax) - [How to Write a Developer Bio (With 2026 Examples)](https://devbio.me/blogs/developer-bio-components) - [Markdown Anchor Link: Why {#id} Breaks on GitHub](https://devbio.me/blogs/markdown-anchor-link) - [Markdown Table of Contents: Why Your Links 404](https://devbio.me/blogs/markdown-table-of-contents) - [Markdown Nested List: Why Two Spaces Isn't Enough](https://devbio.me/blogs/markdown-nested-list) - [Markdown Code Block: Syntax, Languages, Nesting](https://devbio.me/blogs/markdown-code-block) ![black curved fan-like stacked shapes](https://images.unsplash.com/photo-1726910133626-9b573eca70ff?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w4OTM1MDJ8MHwxfHNlYXJjaHwyfHxmb2xkZWQlMjBwYXBlciUyMGxheWVycyUyMG1pbmltYWwlMjBkYXJrfGVufDB8MHx8fDE3OTAxMjU4Mjh8MA&ixlib=rb-4.1.0&q=80&w=1080) *Photo by [Philip Oroni](https://unsplash.com/@philipsfuture?utm_source=quillly&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=quillly&utm_medium=referral)* You pasted a collapsible section into your README, hit preview, and the toggle works — but everything inside it came out as raw asterisks and dashes. Your bullet list is plain text. Your bold is literally `**bold**`. **One blank line fixes it.** A Markdown collapsible section is an HTML `
` element, and Markdown inside an HTML block is only parsed again after a blank line. Put an empty line between `` and your content, and the bullets, bold, tables, and headings all render. Leave it out and the parser copies everything through untouched. That single rule explains most of what goes wrong here. The rest of this piece shows the proof, the platforms where the whole thing gets stripped anyway, and five patterns worth copying. ## A Markdown Collapsible Section Is HTML, Not Markdown Start here, because it saves you hunting for one: **no Markdown flavor has a native collapsible syntax.** Not CommonMark, not GitHub Flavored Markdown, not MultiMarkdown. There is no `>>>` toggle, no `:::details` fence in standard Markdown, no shorthand at all. What you use instead is plain HTML — two elements that have been in the HTML standard for years: ```
Click to expand Hidden content goes here.
``` `
` is the container. `` is the always-visible label you click. The browser supplies the open/close behavior with zero JavaScript, which is why it works inside a README where scripts are stripped. The [WHATWG HTML standard](https://html.spec.whatwg.org/multipage/interactive-elements.html) defines the element, and [browser support](https://caniuse.com/details) is universal on current engines. This is the same situation as [centering text in Markdown](https://devbio.me/blogs/markdown-center-text) or [underlining it](https://devbio.me/blogs/underline-in-markdown): the syntax you want doesn't exist, so you drop to HTML and inherit HTML's rules. And HTML's rules inside Markdown are where the blank line comes in. ## Why the Blank Line Is Load-Bearing When a Markdown parser sees a line starting with `
`, it stops parsing Markdown. Per the [CommonMark spec](https://spec.commonmark.org/0.31.2/), that starts an **HTML block**, and an HTML block runs until a blank line. Everything inside it is copied to the output verbatim — asterisks, hyphens, pipes and all. A blank line ends the HTML block. The content after it is parsed as normal Markdown again. Then `
` starts a fresh HTML block of its own. ![Flowchart showing how a Markdown parser treats a details block with and without a blank line after the summary tag](https://quillly.com/serve/v1/019e3623-8b91-738d-ae30-42d5bcd996a0/images/603d15e4ec4be54429633a67522e49367b684e40.webp) So the blank line isn't a style preference or a quirk of GitHub. It's the documented boundary of an HTML block in the spec every major renderer implements. ## The Proof, Side by Side I ran both versions of the Markdown collapsible section through markdown-it 14.3.2 with HTML enabled — the same CommonMark-compliant parsing GitHub and most static site generators build on. Here is the exact output. **Without a blank line** after ``, the input: ```
Click to expand **Bold text** and a list: - one - two
``` produces this HTML: ```
Click to expand **Bold text** and a list: - one - two
``` Nothing was parsed. The asterisks and hyphens are still asterisks and hyphens, and the reader sees them. **With a blank line**, the same content produces: ```
Click to expand

Bold text and a list:

  • one
  • two
``` Real ``, a real `
    `. One empty line is the entire difference. ![Side-by-side comparison cards showing broken output without a blank line and correct output with one](https://quillly.com/serve/v1/019e3623-8b91-738d-ae30-42d5bcd996a0/images/6a4e97f9c7a04490e52d8f531acd293007d09c1b.webp) A closing blank line before `
` is good hygiene for the same reason, though in practice the content block has usually already been closed by then. ## Why Bold in Your Summary Stays Literal Here's the one that catches people who already know the blank line rule. This input: ```
**Bold summary?** Body.
``` renders the summary as the literal text `**Bold summary?**` — asterisks visible. I verified it; the output keeps them. The reason follows directly from the rule above. The `` line sits *inside* the opening HTML block, before any blank line has ended it. Markdown is not being parsed on that line at all, so `**` is just two characters. You cannot fix this with a blank line, because a blank line there would break the `` away from its `
`. **Use HTML inside the summary instead:** ``` Bold summary ``` ``, ``, `` and `` all work there. It's HTML inside HTML, which is exactly what the parser expects. ## Where a Markdown Collapsible Section Gets Flattened The `
` element survives anywhere raw HTML is allowed through. It disappears anywhere HTML is sanitized — and the failure is quiet, which is what makes it dangerous. | Surface | Collapsible works? | What you get if not | | --- | --- | --- | | GitHub README / issues / PRs | Yes | — | | GitHub Gists | Yes | — | | GitLab | Yes | — | | Static site generators (HTML enabled) | Yes | — | | Renderers with HTML disabled | No | Tags print as visible text | | Sanitized renderers (npm, many CMSs) | No | Content shown, always expanded | | Reddit / Slack / Discord | No | Raw tags or nothing | | devbio.me bio fields | No | Tags print as visible text | Two of those rows deserve the detail, because they fail in genuinely different ways. **HTML disabled.** Some renderers run with raw HTML switched off for safety. I ran the blank-line version through markdown-it with `html: false` and got this: ```

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

Bold text and a list:

... ``` The tags are escaped and **printed on the page** as visible `
` text. Your content renders fine; the widget becomes literal garbage above and below it. This is the same failure mode as [an HTML comment that shows up on the page](https://devbio.me/blogs/markdown-comment-syntax). **Sanitized.** I passed the correct, working HTML through sanitize-html 2.17.7 at its defaults. Neither `details` nor `summary` is in that library's default allowed-tags list, so both tags were **removed while their contents were kept**: ``` Click to expand

Bold text and a list:

  • one
  • two
``` Nothing looks broken. There's just no toggle any more — everything you meant to hide is permanently visible, with the summary text dangling above it as a stray line. If you use a collapsible section to tuck away a long install log, a sanitized renderer publishes that log in full. ![Bar chart comparing how many of eight common publishing surfaces support collapsible sections, disable HTML, or sanitize the tags away](https://quillly.com/serve/v1/019e3623-8b91-738d-ae30-42d5bcd996a0/images/35b85d195cbf3f898bfda0686309e0df7d1c24e9.webp) Want a profile page where your links, stack and live project proof render properly without fighting a sanitizer? [See what a devbio profile shows](https://devbio.me). ## What Happens on devbio.me Bio Fields Worth being specific about our own surface, since people do paste READMEs into it. The devbio About block runs a deliberately tiny inline renderer. It splits your text into paragraphs on blank lines, then handles exactly three things: `**bold**`, `*italic*`, and `[text](https://url)` links. Everything else is emitted as plain text and escaped by React. So a `
` block pasted into an About field shows the literal characters `
` and `Click to expand` to every visitor. It isn't stripped, and it isn't rendered — it's printed. The tradeoff is intentional: no raw HTML from user input means no injected markup on anyone's profile. If you need collapsible content on a profile, structure it with real fields rather than hiding it behind a toggle. A [developer bio](https://devbio.me/blogs/developer-bio-components) that needs a spoiler tag is usually a bio that needs cutting. ## Five Patterns That Actually Work All five Markdown collapsible section patterns below are verified against markdown-it 14.3.2 with HTML enabled. **1. Open by default.** Add the `open` attribute and the section starts expanded — useful when you want it collapsible but not hidden: ```
Already expanded ## A heading inside Text.
``` Headings render normally inside. That `

` came out as a real `

`. Linking to it from outside the block is the risky part: put the anchor on the line above `
` instead of inside it, for the reasons in our [markdown anchor link guide](https://devbio.me/blogs/markdown-anchor-link). **2. Nested toggles.** Nesting works, as long as every level gets its blank lines: ```
Outer
Inner Inner body.
``` **3. Tables inside.** A [Markdown table](https://devbio.me/blogs/markdown-table-of-contents) renders fine once the blank line is there — I confirmed it emits a full `` with `` and ``. This is the most useful pattern for a README: a comparison table that doesn't dominate the page. **4. Inside a list item.** Indent the whole block to match [the list item's content column](https://devbio.me/blogs/markdown-nested-list) and it works: ``` - Item
Nested in list Body text.
``` **5. Code blocks inside.** Fenced [code blocks](https://devbio.me/blogs/markdown-code-block) work normally after the blank line. This is the classic README use — hiding a long config file or stack trace behind one line. ![Checklist card summarising the five working collapsible section patterns and the two rules that make them work](https://quillly.com/serve/v1/019e3623-8b91-738d-ae30-42d5bcd996a0/images/7c42235c2ed7d7cc02fae63930d5fe3e68ea8f80.webp) ## Debugging Yours in Under a Minute ![Table mapping each collapsible section symptom to its cause and whether you can fix it in your Markdown](https://quillly.com/serve/v1/019e3623-8b91-738d-ae30-42d5bcd996a0/images/6f6b3e9753ffbb1d7855ccf5dd3ffbc2f08e3ec2.webp) Collapsible Markdown fails in four distinct ways, and the symptom tells you which one you have. Work down this list: - **Toggle works, content shows raw `**` and `-`** → missing blank line after ``. The fix is one keystroke. - **Summary label shows literal asterisks** → Markdown isn't parsed on the summary line. Swap to ``. - **You see the words `
` and `` on the page** → the renderer has raw HTML disabled. No edit to your Markdown will fix that; the surface won't do it. - **No toggle, but all the content is there** → a sanitizer removed the tags. Same conclusion: pick a different structure for that surface. - **Nothing renders at all** → check you closed `
`, and that you used `` rather than ``. The middle two aren't bugs in your Markdown. They're the platform telling you it doesn't allow raw HTML, and the only real fix is to stop depending on it there. [Put your links, stack and live project proof on one page](https://devbio.me) — no HTML required. ## Frequently Asked Questions ### Is there a pure Markdown way to make a collapsible section? No. No Markdown specification — CommonMark, GitHub Flavored Markdown, or otherwise — defines a collapsible or toggle syntax. Every working approach uses the HTML `
` and `` elements. Some documentation platforms add their own custom directive, but that syntax only works inside that platform. ### Why does my bold text show as asterisks inside the details block? Because there is no blank line after ``. Without it, the parser treats your whole block as raw HTML and copies the Markdown through unparsed. Add one empty line between `
` and your content and the bold, lists and tables all render correctly. ### Can I put a Markdown table inside a collapsible section? Yes, provided the blank line is there. I confirmed markdown-it emits a complete `
` with `` and `` inside the `
` element. It's one of the best uses of the pattern — a long comparison table that doesn't dominate the README. ### Does a collapsible section work on npm or PyPI package pages? Usually not as a toggle. Those pages sanitize README HTML, and `details` and `summary` are not in the default allowed-tags list of common sanitizers. The tags are removed but the content is kept, so your hidden section renders permanently expanded instead of vanishing. ### How do I make a collapsible section open by default? Add the `open` attribute to the opening tag: `
`. The section renders expanded on load and can still be collapsed by clicking the summary. It's a standard HTML boolean attribute, so no value is needed. ### Can collapsible sections be nested? Yes. Put a complete `
` block inside another one, and give every level its own blank line after each ``. Verified working — the inner block's Markdown parses correctly. Keep it to two levels; deeper nesting gets hard to click through. ### Is a Markdown dropdown the same as a collapsible section? Yes — people search for a Markdown dropdown, a toggle, an accordion, a spoiler and a collapsible section, and on GitHub all five mean the same `
` and `` pair. There's no separate dropdown syntax. The only real distinction is a true `