Inline HTML in Markdown

To use raw HTML in Markdown, write the HTML tags directly in your document, and the parser passes them through to the output untouched. Markdown was designed this way, so you can drop in an inline tag such as <sub> or a block such as <div> when Markdown has no syntax for what you need. Most flavors allow this, though the rules differ between inline HTML and block-level HTML, and hosted renderers may sanitize unsafe tags.

Inline HTML in Markdown syntax reference

Inline HTML in Markdown key facts

• Markdown passes raw HTML straight through to the output, so any tag works wherever the renderer allows it.
• Inline HTML sits inside a paragraph, while block-level HTML starts on its own line and is treated as a raw HTML block.
• By default, Markdown inside a raw HTML block is not processed, and Markdown Extra opts in with the markdown="1" attribute.
• HTML entities such as ©, <, and & are the safe way to write reserved characters inside Markdown.
• Hosted renderers like GitHub sanitize output and strip unsafe tags such as <script> and <style>, so those never execute.
• Slack, Discord, Reddit, and Notion do not support raw HTML passthrough and show tags as literal text.

Use inline HTML as a compatibility decision

Raw HTML can fill gaps in Markdown, such as <details>, <mark>, custom image sizes, or richer table structures. It also reduces portability. Some renderers allow it, some escape it, and security-focused platforms sanitize particular tags and attributes.

Prefer ordinary Markdown when it expresses the same structure. Use HTML only when the target system is known and the fallback has been considered. Never assume that scripts, event handlers, iframes, or style attributes will survive publishing. For content moving between GitHub, a documentation site, and a note app, test the rendered result and the exported HTML.

Basic syntax

Write the HTML tag where you want it. Inline tags sit inside a paragraph and mix with surrounding text. Block-level tags start on their own line and are treated as a raw HTML block.

Markdown

This word is <strong>bold via HTML</strong> in the middle of a sentence.

<div class="note">
  A block-level HTML element on its own lines.
</div>

Rendered output

HTML output

<p>This word is <strong>bold via HTML</strong> in the middle of a sentence.</p>
<div class="note">
  A block-level HTML element on its own lines.
</div>

Raw HTML is passed straight to the output. The inline <strong> sits inside the paragraph, and the <div> becomes a raw HTML block that Markdown leaves as-is.

Inline HTML

Inline HTML tags appear within a line of text, alongside normal words and Markdown formatting. They are useful for elements Markdown does not define, such as <sub>, <sup>, <kbd>, and <abbr>.

Markdown

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy. Water is H<sub>2</sub>O.

Rendered output

HTML output

<p>Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy. Water is H<sub>2</sub>O.</p>

When a tag is not on a line by itself, most parsers treat it as inline raw HTML inside the surrounding paragraph, and Markdown formatting around it still works.

Block-level HTML

A block-level HTML element that starts on its own line is treated as a raw HTML block. In CommonMark and GFM, when a tag such as <div> sits on a line by itself, the parser opens a raw HTML block and passes everything through until the block closes.

Markdown

<table>
  <tr>
    <th>Name</th>
    <th>Role</th>
  </tr>
  <tr>
    <td>Ada</td>
    <td>Engineer</td>
  </tr>
</table>

Rendered output

HTML output

<table>
  <tr>
    <th>Name</th>
    <th>Role</th>
  </tr>
  <tr>
    <td>Ada</td>
    <td>Engineer</td>
  </tr>
</table>

Markdown inside a raw HTML block

By default, Markdown inside a raw HTML block is not processed. If you write **bold** inside a <div>, most parsers, including CommonMark, leave it as literal text rather than converting it.

Markdown

<div>
**This is not converted to bold by default.**
</div>

Rendered output

<div markdown="1">
**This is converted to bold in Markdown Extra.**
</div>

HTML entities

HTML entities work inside Markdown and are the safe way to write reserved characters such as <, >, and &, or symbols such as the copyright sign.

Markdown

© 2026 Markdific. Use < and > for angle brackets, and & for an ampersand.

Rendered output

HTML output

<p>&copy; 2026 Markdific. Use &lt; and &gt; for angle brackets, and &amp; for an ampersand.</p>

Flavor differences

Passing HTML through is part of Markdown's original design, and CommonMark specifies it precisely. The main differences are whether a flavor processes Markdown inside HTML blocks and whether a renderer sanitizes or strips raw HTML for security.

The major Markdown specifications covered here define some form of raw HTML passthrough, but publishing systems may disable or sanitize it. The differences are meaningful in two areas. First, processing Markdown inside an HTML block: CommonMark, GFM, and most flavors do not do it, while Markdown Extra opts in through markdown="1". Second, sanitization: GitHub filters rendered HTML and removes unsafe elements such as <script> and <style>, so raw HTML that runs code will not execute on GitHub even though the tag passes the parser. Always assume a hosted renderer may strip or sanitize HTML you did not expect.

Other platforms (Slack, Discord, Reddit, Notion)

• Slack and Discord: do not support raw HTML. Tags appear as literal text, since these platforms use their own limited formatting rather than Markdown HTML passthrough.
• Reddit: does not allow raw HTML in comments or posts. HTML tags are shown as plain text.
• Notion: does not render pasted raw HTML as live elements in normal text blocks. It maps supported Markdown to its own blocks instead.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific processes Markdown documents that may contain raw HTML. Raw HTML handling, including which tags pass through and how unsafe elements such as <script> and <style> are treated, varies by renderer and is not defined by the core Markdown standard.

Because raw HTML behavior and sanitization differ across tools, treat HTML in a portable document with care and verify it renders as intended in your target.

Try it in the Markdific online editor.

Common mistakes and gotchas

• Expecting Markdown inside HTML blocks. By default, **bold** inside a <div> stays literal. Use Markdown Extra's markdown="1", or write the inner HTML directly.
• No blank line around block HTML. Some parsers need a blank line before and after a block-level HTML element to separate it cleanly from surrounding Markdown.
• Assuming HTML always renders. Chat and note tools such as Slack, Discord, Reddit, and Notion show raw HTML as literal text.
• Relying on unsafe tags. Renderers such as GitHub sanitize output and strip <script>, <style>, and other unsafe elements, so they will not run.
• Unclosed tags. An unclosed block-level tag can pull following content into the raw HTML block and break the layout.
• Using HTML where Markdown suffices. Reach for raw HTML only when Markdown has no equivalent. Prefer Markdown syntax for portability and readability.

Best practices

• Use raw HTML only for what Markdown cannot express, such as <sub>, <sup>, <kbd>, and complex tables.
• Put block-level HTML on its own lines, with a blank line before and after.
• Use HTML entities for reserved characters like <, >, and &.
• Remember that Markdown inside a raw HTML block is not processed unless the flavor supports markdown="1".
• Expect hosted renderers to sanitize HTML, so never rely on scripts or unsafe tags.
• Keep documents portable by minimizing raw HTML when the content may move between platforms.

HTML equivalent

Inline HTML is already HTML, so it passes through to the output unchanged. Markdown around it still compiles normally, and the raw tags are emitted as written.

Markdown

A footnote marker<sup>1</sup> and a shortcut <kbd>Esc</kbd>.

<div class="callout">Raw block element.</div>

HTML output

<p>A footnote marker<sup>1</sup> and a shortcut <kbd>Esc</kbd>.</p>
<div class="callout">Raw block element.</div>

FAQ

Can you use HTML inside Markdown? Yes. Markdown was designed to pass raw HTML through, so you can write inline tags such as <sub> or block-level elements such as <div>. Most flavors support this, though hosted renderers may sanitize unsafe tags.

Is Markdown inside an HTML block processed? No, not by default. In CommonMark, GFM, and most flavors, Markdown inside a raw HTML block stays literal. Markdown Extra adds the markdown="1" attribute to opt into processing the inner Markdown.

What is the markdown="1" attribute? It is a Markdown Extra feature. Adding markdown="1" to a block-level HTML tag tells the parser to convert the tag's content from Markdown to HTML. It is not part of CommonMark or GitHub Flavored Markdown.

What is the difference between inline and block HTML? Inline HTML is a tag within a line of text that mixes with surrounding words. Block-level HTML starts on its own line and is treated as a raw HTML block that the parser passes through until it closes.

Does GitHub allow raw HTML in Markdown? Yes, with filtering. GitHub follows CommonMark for HTML passthrough but sanitizes the output and strips unsafe elements such as <script> and <style>, so those tags will not execute.

Do HTML entities work in Markdown? Yes. Entities such as ©, &, <, and > render as their characters and are the safe way to write reserved symbols inside Markdown.

Does raw HTML work in Slack, Discord, or Reddit? No. Those platforms do not support raw HTML passthrough. HTML tags appear as literal text because they use their own limited formatting rather than Markdown's HTML handling.

When should you use HTML instead of Markdown? Reach for raw HTML only when Markdown has no equivalent, such as <kbd>, <abbr>, complex tables with merged cells, or a <div> wrapper for layout. For anything Markdown can express, prefer Markdown syntax, since it is more portable and readable.

Why is my raw HTML showing as literal text instead of rendering? Either the platform does not pass HTML through, as with Slack, Discord, Reddit, and Notion, or a hosted renderer sanitized and stripped the tag. Confirm the target supports HTML passthrough and that the tag is not on the unsafe list.

Do you need a blank line around block-level HTML in Markdown? It is safest to add one. Some parsers need a blank line before and after a block-level HTML element to separate it cleanly from surrounding Markdown, and an unclosed tag without that spacing can pull following content into the raw HTML block.

How do you center text or an image in Markdown? Markdown has no alignment syntax, so use raw HTML where the renderer allows it, for example wrapping the content in a <div align="center"> or <p align="center">. Note that GitHub and other hosts may strip some attributes during sanitization.

Sources and compatibility references

• CommonMark 0.31.2: raw HTML
• GFM specification: disallowed raw HTML

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Escaping characters in Markdown
• Inline code in Markdown
• Subscript and superscript
• Tables in Markdown
• Markdown flavors compared