HTML Tags You Can Use in Markdown Documents

What Works (with Examples)

A definitive reference for using HTML inside GitHub Flavored Markdown (GFM) documents on GitHub.
Includes allowed tags, examples, best practices, and references.

---

📚 Table of Contents

• 🚦 Key Rules
• 📑 Headings
• ✍ Text Emphasis & Edits
• 🔢 Superscript & Subscript
• ⌨ Code & Preformatted
• 💬 Quotes
• 🔗 Links
• 🖼 Images
• 📋 Lists
• 📊 Tables
• 📖 Definition Lists
• 📏 Horizontal Rules & Breaks
• 📦 Block Containers & Alignment
• 📂 Collapsible Sections
• 🈶 Ruby Annotations
• ❌ What’s NOT Allowed
• ✅ Quick Reference Table
• ⚠️ Gotchas & Best Practices
• 🔗 References
• 📄 License

---

🚦 Key Rules

• ❌ Not allowed: <script>, <style>, <iframe>, <embed>, <object>
• ❌ Inline CSS styles, class, and id are stripped by sanitization
• ✅ Allowed attributes: href, src, title, alt, width, height, align, target, lang, itemscope, itemtype, itemprop
• ✅ Safe URL schemes: http, https, mailto, and relative (./file.md)
• ✅ Collapsibles work: <details><summary> supported across README/issues/PRs

Prefer Markdown for most formatting. Use HTML only when Markdown can’t express your intent (e.g., collapsibles, ruby annotations, complex tables, keyboard keys).

---

📑 Headings

<h1>Main Title</h1>
<h2>Section</h2>

For example:

Main Title

Section

(Prefer # Markdown headings for readability; HTML headings are fine when needed inline.)

---

✍ Text Emphasis & Edits

<b>Bold</b> <strong>Strong</strong>
<i>Italic</i> <em>Emphasis</em>
<s>Strike</s> <del>Deleted</del>
<ins>Inserted</ins>
<mark>Highlight</mark>

For example:
Bold, Strong, Italic, Emphasis, Strike, Deleted, Inserted, Highlight

---

🔢 Superscript & Subscript

E = mc<sup>2</sup>, H<sub>2</sub>O

For example:
E = mc², H₂O

---

⌨ Code & Preformatted

<code>npm install</code>

<pre>
line 1
line 2
</pre>

<kbd>Ctrl</kbd> + <kbd>C</kbd>
<samp>output sample</samp>
<var>x</var>
<tt>Monospace text</tt>

For example:
npm install

line 1
line 2

Ctrl + C
output sample
x
Monospace text

---

💬 Quotes

<q cite="https://example.com">Inline quote</q>

<blockquote cite="https://example.com">
  Block quote example with citation.
</blockquote>

For example:
Inline quote

Block quote example with citation.

---

🔗 Links

<a href="https://github.com" title="GitHub" target="_blank">GitHub</a>

For example:
GitHub

---

🖼 Images

<img src="https://placehold.co/120x80.png" alt="Placeholder" width="120" height="80" title="Example image">

For example:

---

📋 Lists

<ol>
  <li>First</li>
  <li>Second</li>
</ol>

<ul>
  <li>A</li>
  <li>B</li>
</ul>

For example:

1. First
2. Second

• A
• B

---

📊 Tables

<table>
  <thead>
    <tr><th>Col1</th><th>Col2</th><th>Col3</th></tr>
  </thead>
  <tbody>
    <tr><td rowspan="2">Rowspan</td><td>A</td><td>B</td></tr>
    <tr><td colspan="2">Colspan example</td></tr>
  </tbody>
  <tfoot><tr><td colspan="3">Footer</td></tr></tfoot>
</table>

For example:

Col1	Col2	Col3
Rowspan	A	B
	Colspan example
Footer

---

📖 Definition Lists

<dl>
  <dt>Term</dt>
  <dd>Definition</dd>
</dl>

For example:

Term

Definition

---

📏 Horizontal Rules & Line Breaks

<hr>
Line 1<br>Line 2

For example:

---

Line 1
Line 2

---

📦 Block Containers & Alignment

<div align="center">
  <p>Centered paragraph</p>
  <img src="https://placehold.co/80x80.png" alt="icon">
</div>

For example:

Centered paragraph

---

📂 Collapsible Sections

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

  You can include **Markdown**, lists, code blocks, and images inside.

  ```bash
  echo "Hello"

```

For example:

Click to expand

You can include Markdown, lists, code blocks, and images inside.

echo "Hello"

Tips:

• Leave a blank line after <summary> for Markdown to render inside.
• Leave a blank line before </details> for consistency.

---

🈶 Ruby Annotations

<ruby>漢<rt>hàn</rt></ruby>
<ruby>漢<rp>(</rp><rt>hàn</rt><rp>)</rp></ruby>

For example:
漢hàn
漢(hàn)

---

❌ What’s NOT Allowed

• <script>, <style>, <iframe>, <embed>, <object> → stripped
• Inline CSS styles (style="...") and class/id → stripped
• Unsafe link schemes (javascript:, vbscript:) → stripped
• <video> and <audio> not consistently supported

---

✅ Quick Reference Table

Tag	Allowed?	Attributes	Notes
<a>	✅	href, title, target	Safe schemes only
<img>	✅	src, alt, width, height, title	style/class stripped
<details>/<summary>	✅	open	Great for collapsibles
<sup>/<sub>	✅	–	Good for math, chemistry
<kbd>/<code>/<pre>	✅	–	For code & input
<table> + children	✅	colspan, rowspan, align	Complex tables work
<div>	✅	align, itemscope, itemtype	style/class ignored
<ruby>/<rt>/<rp>	✅	–	East Asian annotations
<script>/<iframe>/<style>	❌	–	Removed

---

⚠️ Gotchas & Best Practices

• Prefer Markdown where possible
• Always preview on GitHub.com
• Use blank lines around HTML blocks for reliable parsing
• Blank lines around <details> content improve parsing
• Stick to safe, absolute or relative links

---

🔗 References

• GitHub Docs – Writing on GitHub: https://docs.github.com/github/writing-on-github
• GitHub Docs – Basic writing and formatting syntax: https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
• StackOverflow – Allowed HTML tags in GitHub Markdown: https://stackoverflow.com/questions/14951321/how-to-display-html-content-in-github-readme-md
• StackOverflow – Which inline HTML styles are allowed: https://stackoverflow.com/questions/44831505/which-inline-html-styles-does-github-markdown-accept
• Advanced Markdown Examples: https://github.com/DavidWells/advanced-markdown
• CC BY 4.0 License: https://creativecommons.org/licenses/by/4.0/

---

📄 License

Creative Commons Attribution 4.0 International (CC BY 4.0)
You are free to share and adapt, including commercial use, with attribution.
See: https://creativecommons.org/licenses/by/4.0/

Last Verified: 2025‑09‑11 (America/Chicago)
Confidence: High