HTML-Tags-Supported-in-GitHub-Flavored-Markdown-Documents

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
🤝 How to Contribute
🔗 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:
Placeholder

📋 Lists

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

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

For example:

First
Second

📊 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
Rowspan	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"

</details>

For example:  
<details><summary>Click to expand</summary>

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

```bash
echo "Hello"

</details>

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

🤝 How to Contribute

See CONTRIBUTING.md for guidelines.
By contributing, you agree your contributions are licensed under CC BY 4.0.

🔗 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

This site is open source. Improve this page.