Markdown HTML Block
How to embed raw HTML in markdown for elements not natively supported. Syntax, security considerations, and platform support.
What is markdown 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.
Syntax
Inline HTML
Inline HTML elements can be mixed with markdown text.
Block HTML
Block-level HTML must be preceded and followed by a blank line.
Details/summary
Native HTML collapsible section — commonly used in GitHub READMEs.
Click to expand
Hidden content here.Platform support
| Platform | Supported | Notes |
|---|---|---|
| GitHub | Yes | Sanitized — style attributes and scripts removed |
| GitLab | Yes | Sanitized HTML |
| Obsidian | Yes | — |
| Discord | No | HTML rendered as plain text |
| Slack | No | — |
| Notion | No | Does not render raw HTML |
Common mistakes
<div>content</div> (no blank lines)
<div>content</div>
Block-level HTML elements need blank lines before and after them to be parsed as HTML blocks rather than inline HTML.
Tips for html block
By default, markdown is not parsed inside HTML block elements. Use the markdown="1" attribute in some parsers (Kramdown) to enable it.
GitHub strips style= attributes for security. Use class attributes with your own CSS, or rely on native GitHub rendering.
Frequently asked questions
Everything you need to know.
Can I use inline CSS in markdown?
On platforms that allow HTML, yes: <span style="color:red">text</span>. However, GitHub strips style attributes for security. Check your platform's HTML sanitization policy.
Related elements
Escape Character
The backslash (\) is markdown's escape character. Placing a backslash before a markdown special character causes it to be displayed literally instead of being interpreted as formatting syntax. This is essential when you need to show asterisks, hashes, underscores, or other special characters as plain text.
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.
Keyboard Input
Keyboard input formatting uses the HTML <kbd> tag to display key names and shortcuts in a styled box that visually represents a physical key. It is commonly used in documentation and tutorials to indicate what keys to press.
YAML Frontmatter
YAML frontmatter is a block of YAML metadata placed at the very top of a markdown file, between two sets of triple dashes (---). It stores structured data about the document — title, date, author, tags, layout — separate from the content. Static site generators like Jekyll, Hugo, and Astro use frontmatter to control page rendering.
Try it in the editor
Paste your markdown and see html block rendered instantly with professional themes.