HTML in Markdown: When and How to Use Raw HTML

Markdown allows raw HTML for features the syntax does not cover. Need a collapsible section? Use <details>. Need keyboard shortcuts? Use <kbd>. Need custom alignment? Use a <div>. But not every platform allows every tag, and security restrictions vary widely.

This guide covers which HTML tags are practical in markdown, what each platform supports, and when HTML is the right choice.

When to Use HTML in Markdown

HTML fills gaps in the markdown spec. The most common reasons to reach for HTML:

1. Collapsible sections (no markdown equivalent)
2. Image sizing (markdown has no width/height syntax)
3. Keyboard shortcuts (<kbd> styling)
4. Subscript and superscript (chemical formulas, math)
5. Definition lists (not in GFM)
6. Custom alignment (centering content)
7. Semantic elements (<figure>, <figcaption>, <abbr>)

Practical HTML Tags for Markdown

Collapsible Sections (<details>)

The most useful HTML tag in markdown. Creates a toggle section:

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

Hidden content goes here. You can use **markdown** inside.

- List items work
- Code blocks work

</details>

The blank line after <summary> is required for markdown processing inside the block.

This works on GitHub, VS Code, and most renderers that allow HTML. It does not work in Obsidian.

Keyboard Shortcuts (<kbd>)

Renders key-cap styled text:

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.
Save with <kbd>Cmd</kbd> + <kbd>S</kbd> on macOS.

Supported on GitHub, VS Code, and MDtoLink. Stripped in some sanitized environments.

Image Sizing (<img>)

Standard markdown has no sizing syntax. Use the HTML tag:

<img src="/images/logo.png" alt="MDtoLink logo" width="200" />
<img src="/images/screenshot.png" alt="Editor" width="600" height="400" />

Set only width to preserve aspect ratio. GitHub allows <img> with width, height, alt, and src attributes.

Subscript and Superscript

H<sub>2</sub>O
E = mc<sup>2</sup>
x<sup>n</sup> + y<sup>n</sup> = z<sup>n</sup>

Supported on GitHub and most platforms that allow HTML.

Centered Content

<div align="center">

# Centered Heading

Centered paragraph text.

<img src="/images/logo.png" alt="Logo" width="200" />

</div>

The align attribute on <div> works on GitHub. The blank lines inside the div are required for markdown processing.

Definition Lists (<dl>)

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for formatting plain text.</dd>

  <dt>GFM</dt>
  <dd>GitHub Flavored Markdown, an extension of CommonMark.</dd>
</dl>

Some parsers strip <dl>, <dt>, and <dd> tags. Test on your target platform.

Figures with Captions (<figure>)

<figure>
  <img src="/images/chart.png" alt="Growth chart" />
  <figcaption>Figure 1: Monthly active users, Jan-Jun 2026</figcaption>
</figure>

GitHub strips <figure> and <figcaption> tags. This works in VS Code preview, MDtoLink, and raw HTML renderers.

Abbreviations (<abbr>)

<abbr title="GitHub Flavored Markdown">GFM</abbr> extends CommonMark.

Shows a tooltip on hover. Supported in most environments that allow HTML.

Line Breaks (<br>)

Line one<br>
Line two (no paragraph gap)

More reliable than the two-trailing-spaces method for forced line breaks.

Colored Text (Limited Support)

<span style="color: red">Warning text</span>

GitHub strips style attributes for security. This only works in environments that pass through raw HTML without sanitization.

Important Rules for HTML in Markdown

Blank lines around block-level HTML. Block elements (<div>, <details>, <table>) need blank lines before and after for markdown to process correctly:

Some markdown text.

<details>
<summary>Details</summary>

Markdown inside the block.

</details>

More markdown text.

Blank lines inside block HTML for markdown processing. If you want markdown formatting inside an HTML block, add blank lines after the opening tag:

<div>

**This markdown is processed** because of the blank line above.

</div>

Without the blank line, some parsers treat the content as raw HTML and skip markdown processing.

Inline HTML does not need blank lines. Tags like <kbd>, <sub>, <sup>, <br>, <img>, and <span> work inline without special spacing.

Security Restrictions by Platform

Different platforms sanitize HTML differently:

Always stripped for security: <script>, <iframe>, <style>, <form>, <input>, and inline JavaScript event handlers.

GitHub is the most common target for markdown with HTML. Its allow-list includes: <details>, <summary>, <kbd>, <img>, <sub>, <sup>, <br>, <hr>, <div>, <table>, <thead>, <tbody>, <tr>, <th>, <td>, <pre>, <code>, <a>, <b>, <i>, <em>, <strong>, <del>, <ins>, <ul>, <ol>, <li>, <dl>, <dt>, <dd>, <p>, <h1> through <h6>.

HTML Tables vs Markdown Tables

For simple tables, markdown is cleaner. For complex tables (colspan, rowspan, nested content), HTML is required:

<table>
  <tr>
    <th>Feature</th>
    <th colspan="2">Pricing</th>
  </tr>
  <tr>
    <td>Storage</td>
    <td>5 GB</td>
    <td>Unlimited</td>
  </tr>
</table>

Markdown tables do not support merged cells, multi-line cell content, or nested tables.

FAQ

Can I use HTML inside markdown?

Yes. Most markdown processors pass HTML through to the output. Block-level HTML (<div>, <details>, <table>) needs blank lines before and after. Inline HTML (<kbd>, <br>, <sub>) works within paragraphs.

What HTML tags does GitHub allow in markdown?

GitHub allows structural and formatting tags: <details>, <summary>, <kbd>, <img>, <sub>, <sup>, <div>, <table>, <a>, and basic text tags. It strips <script>, <iframe>, <style>, <form>, and inline event handlers for security.

Why does my HTML not render in Obsidian?

Obsidian has limited HTML support. It strips many block-level tags (<details>, <div>, <figure>) and does not process align attributes. For Obsidian-specific features, use its native callout syntax (> [!NOTE]) instead of HTML.

Should I use HTML or markdown for tables?

Use markdown tables for simple data (columns and rows with text). Use HTML tables when you need merged cells (colspan/rowspan), multi-line cell content, or styling that markdown tables cannot express.

Try It Out

Test HTML tags in the MDtoLink editor to see what renders. Publish your document to a shareable URL when it’s ready.

For the full syntax reference, see the markdown cheat sheet. For image-specific guidance, see the markdown images guide.