Need AI Training/Help?CloudYeti.io/meet
MarkdownMe
Markdown to HTML guide

Embed HTML in Markdown (and When to Mix Them)

Use raw HTML inside Markdown for things Markdown can't express — collapsible sections, keyboard keys, subscript — and know when not to.

Direct answer

Most Markdown renderers pass raw HTML through untouched, so you can drop in tags like <details>, <kbd>, <sub>, or <br> for things plain Markdown can't express. Keep a blank line around block-level HTML, and remember Markdown syntax inside an HTML block often will not render.

Open Markdown to HTML converter

When to use this

  • You need a collapsible <details> section, a keyboard <kbd> key, or subscript/superscript.
  • Markdown can't express the structure you want (colspan, custom attributes).
  • You are mixing Markdown and HTML in a README, static site, or docs page.

Steps

  1. Write your normal Markdown.
  2. Drop in raw HTML tags where Markdown falls short (<details>, <kbd>, <sub>, <br>).
  3. Leave a blank line before and after block-level HTML so surrounding Markdown still parses.
  4. Avoid relying on Markdown syntax inside an HTML block — write that part as HTML too.
  5. Convert and confirm the HTML passed through and the Markdown around it rendered.

Example conversion

Markdown input
Press <kbd>Cmd</kbd> + <kbd>K</kbd> to insert a link.

<details>
<summary>Show details</summary>

This section is collapsible.

</details>

Water is H<sub>2</sub>O.
HTML output
<p>Press <kbd>Cmd</kbd> + <kbd>K</kbd> to insert a link.</p>
<details>
<summary>Show details</summary>
<p>This section is collapsible.</p>
</details>
<p>Water is H<sub>2</sub>O.</p>

Common mistakes

  • Markdown inside a block-level HTML element often will not render; keep a blank line after <summary> or write the inner content as HTML.
  • Some platforms sanitize or strip HTML for security (script, iframe, style), so test on the target renderer.
  • Overusing raw HTML defeats the point of Markdown; reach for it only when Markdown genuinely cannot express the structure.

FAQ

Can I put HTML inside a Markdown file?
Yes. Most renderers pass raw HTML through, so tags like <details>, <kbd>, and <sub> work inline or as blocks. Keep a blank line around block-level HTML.
Why doesn't Markdown render inside my HTML block?
Many parsers stop interpreting Markdown once they enter a block-level HTML element. Add a blank line after the opening tag, or write the inner content as HTML.
Is embedding HTML in Markdown safe?
It depends on the platform. Trusted contexts like your own README are fine, but sites often sanitize HTML and strip <script>, <iframe>, and <style> to prevent injection.

Related Markdown to HTML guides

How to Convert Markdown to HTML

Convert Markdown into clean, semantic HTML — headings, paragraphs, lists, links, and emphasis — ready to paste into a page or CMS.

Convert a README to an HTML Page

Turn a README.md into a standalone HTML page you can host, preview, or embed — headings, code blocks, and tables intact.

Markdown to HTML for Email Newsletters

Convert Markdown into HTML for email newsletters, then inline the styles so it renders in Gmail, Outlook, and Apple Mail.

Markdown to HTML With Inline CSS and Styling

Convert Markdown to HTML and wrap it in styles — inline CSS or a stylesheet — so the exported page looks designed, not raw.

Convert a Markdown Table to an HTML Table

Turn a Markdown pipe table into a full HTML <table> with thead, tbody, and alignment preserved.

Markdown to HTML: CLI vs Online Converter

When to use a command-line tool like pandoc or markdown-it versus a fast, no-login online Markdown to HTML converter.