An HTML block is a section of raw HTML passed through to the rendered output unchanged. It allows authors to use HTML elements not available in Markdown syntax — such as <div>, <details>, or custom components — directly within a Markdown document.
<div>
<p><span style="font-size: 3em; line-height: 1; vertical-align: baseline;">O</span>nce upon a time...</p>
</div>
Once upon a time...
Best Practice
- Use HTML blocks sparingly. They reduce portability and break rendering in environments that sanitise HTML (such as GitHub comments or some CMS platforms).
- Surround HTML blocks with blank lines. Content immediately adjacent to an HTML block may be consumed as part of it depending on the parser.
- Do not write Markdown inside an HTML block — most parsers do not process Markdown within raw HTML tags. Use separate Markdown blocks before and after instead.
Notes
Markdown Processing Inside HTML Blocks
Most parsers stop processing Markdown syntax once they enter an HTML block. This means emphasis, links, and other Markdown constructs inside an HTML block will be passed through as literal characters, not rendered:
<div>
**This is not bold** — it is passed through as literal asterisks.
</div>
To mix Markdown and HTML, structure the content so the Markdown appears outside the HTML tags:
**This is bold** because it is outside the HTML block.
<div class="custom-box">
Raw HTML content here.
</div>
Inline HTML vs Block HTML
An HTML block is a block-level construct — it must be separated from surrounding Markdown by blank lines. Inline HTML (a fragment of HTML inside a paragraph) is a separate element. Block-level elements like <div>, <table>, and <details> typically form HTML blocks; inline elements like <span>, <abbr>, and <kbd> typically appear as inline HTML.
Sanitisation in Hosted Environments
Many hosted Markdown renderers — including GitHub in issue comments and wikis, and some CMS platforms — sanitise HTML to prevent cross-site scripting (XSS) attacks. In sanitised contexts, HTML blocks may be stripped entirely or have unsafe attributes removed. Always verify HTML block support in your target environment.
Markdown Flavour Support
Broadly supported, but sanitisation behaviour varies significantly by renderer and context.
Flavour Support Detail
| Flavour | Support | Notes |
|---|---|---|
| Original Markdown | Yes | HTML pass-through is fundamental to the original spec philosophy. |
| CommonMark | Yes | Precisely specifies seven categories of HTML block with different start/end rules. |
| GitHub Flavored Markdown | Partial | Supported in files (.md); sanitised in comments and wiki pages to prevent cross-site scripting (XSS). |
| Pandoc Markdown | Yes | Passed through to HTML output; converted or stripped for other formats such as LaTeX or EPUB. |
Practical Examples
- Collapsible spoiler section on a book review blog: A
<details>block lets readers choose whether to see spoilers, something core Markdown has no equivalent for.
**Warning: spoilers below.**
<details>
<summary>What happens at the end</summary>
The twist is revealed on the final page — it was the narrator all along.
</details>
Warning: spoilers below.
What happens at the end
The twist is revealed on the final page — it was the narrator all along.- Invisible author's note: An HTML comment is visible in the source file but never shown in the rendered output — useful for leaving reminders to yourself.
<!-- TODO: replace this placeholder photo once the new one is ready -->
The recipe was passed down from my grandmother and has never been written down until now.
The recipe was passed down from my grandmother and has never been written down until now.
- Centred caption below a photo: When Markdown offers no alignment control, a simple HTML element lets you style a caption without affecting the rest of the page.
<p class="caption">The harbour at Portree, photographed in the last light of October.</p>
The harbour at Portree, photographed in the last light of October.