Markdown: Using HTML Inside Markdown

Markdown isn't all-powerful — when the syntax falls short, just write HTML directly.

1. What You'll Learn

• Basic rules for embedding HTML in Markdown
• The difference between inline HTML and block-level HTML
• Common scenarios where HTML fills the gaps
• Edge cases between HTML and Markdown
• Security and compatibility considerations

2. A Frontend Developer's Real Story

(1) Pain Point: Markdown's limits block requirements

Lisa was writing technical docs for her company and needed to show colored status labels (like red "Failed" and green "Passed") inside table cells. Markdown tables don't support background colors or text colors. She tried all sorts of Markdown workarounds, wasted two hours, and eventually had to screenshot the labels and paste the image — but images aren't searchable.

(2) Solution: Write HTML directly in Markdown

Senior engineer Tom told her: "You can write HTML inside Markdown." Lisa used <span> tags with the style attribute to create colored labels. No screenshots needed, the text remains searchable, and it only adds a few lines of HTML.

| Test Case | Status |
|:----------|:------|
| User Login | <span style="color: green;">✅ Passed</span> |
| Payment API | <span style="color: red;">❌ Failed</span> |

3. HTML Rules in Markdown

Markdown was designed as "an easier way to write HTML." As a result, it natively supports embedding HTML in documents:

graph TB
    A[Markdown Document] --> B[Markdown Syntax]
    A --> C[HTML Syntax]
    B --> D[Headings / Lists / Tables]
    C --> E[Block-level HTML]
    C --> F[Inline HTML]
    E --> G[div / table / pre]
    F --> G[span / img / br]

graph TB
    A[Markdown Document] --> B[Markdown Syntax]
    A --> C[HTML Syntax]
    B --> D[Headings / Lists / Tables]
    C --> E[Block-level HTML]
    C --> F[Inline HTML]
    E --> G[div / table / pre]
    F --> G[span / img / br]

(1) Inline HTML

This is a paragraph with <span style="color: red;">red text</span> and
<strong>bold text</strong> (using HTML tags).

Press Ctrl + <br> to break line (<br> is an HTML tag).

▶ Example: Using HTML to achieve what Markdown can't

This is text in regular Markdown.

<kbd>Ctrl</kbd> + <kbd>S</kbd> to save file.

Upgrade to <abbr title="Version 3.0">v3.0</abbr> release.

(3) Common Block-Level HTML Uses

<!-- Custom container -->
<div style="border: 1px solid #ddd; padding: 16px; border-radius: 8px;">
  <h3>Important Update</h3>
  <p>Scheduled maintenance this weekend.</p>
</div>

<!-- Multi-column layout -->
<div style="display: flex; gap: 16px;">
  <div style="flex: 1;">Left column</div>
  <div style="flex: 1;">Right column</div>
</div>

<!-- Styled table -->
<table>
  <tr>
    <th style="background: #4CAF50; color: white;">Name</th>
    <th>Price</th>
  </tr>
  <tr>
    <td>Product A</td>
    <td>$29</td>
  </tr>
</table>

5. Common HTML-Fills-the-Gap Scenarios

▶ Example: HTML doing what Markdown can't

<!-- Open in new tab -->
<a href="https://example.com" target="_blank">Open in new window</a>

<!-- Custom image size -->
<img src="logo.png" width="150" alt="Logo" style="border-radius: 8px;">

<!-- Keystroke styling -->
<kbd>Enter</kbd> or <kbd>Ctrl</kbd> + <kbd>V</kbd>

<!-- Callout with background color -->
<blockquote style="background: #fff3cd; border-left-color: #ffc107;">
  This is a custom-styled callout box.
</blockquote>

6. The Boundary Between HTML and Markdown

(1) Markdown inside block-level HTML usually won't parse

<div>
  **This text will not be bold** (Markdown syntax fails inside div)
  <strong>This text is bold with HTML</strong>
</div>

Exception: Some parsers (like Pandoc) support Markdown parsing inside HTML tags, but GFM (GitHub) does not. To be safe, use HTML syntax throughout block-level HTML tags.

(2) Markdown inside inline HTML

<span style="color: red;">**This text may render bold in some parsers**</span>

▶ Example: Safe vs unsafe mixing

✅ Safe:
- Write Markdown for body text: **bold**
- Use HTML for custom needs: <span style="color: red;">red</span>

❌ Unsafe:
<div style="padding: 8px;">
  **This bold won't work on GitHub**
</div>

7. Security and Compatibility

(1) Don't do this

❌ Unsafe: <script>alert('XSS')</script>
❌ Unsafe: <img src="x" onerror="alert('attack')">
❌ Unsafe: <iframe src="https://malicious-site.com"></iframe>

(2) HTML compatibility checklist

<!-- ✅ Cross-platform compatible -->
<strong>bold</strong>
<em>italic</em>
<kbd>keystroke</kbd>
<br>
<hr>

<!-- ⚠️ Some platforms don't support -->
<details><summary>Collapsible content</summary>Hidden text</details>
<mark>highlighted text</mark>

8. Complete Example: An HTML-Enhanced Markdown Document

HTML-enhanced Markdown document preview:

Product Changelog v3.2:
- Green-styled callout box: summary of updates
- HTML table: module / status / owner (with colored status)
- Keystroke tags: F5 to refresh
- Bash code block: installation command npm install my-app@latest
- Email link: support@example.com (mailto protocol)

Expected result: A product log combining Markdown and HTML — Markdown handles standard structure, HTML handles colors, keystroke styling, and custom containers.

❓ FAQ

📖 Summary

• Markdown natively supports embedding HTML, both inline and block-level
• Block-level HTML needs blank lines before and after; Markdown inside it usually won't parse
• HTML fills gaps for: colors, dimensions, new-tab links, merged cells, keystroke styling
• Avoid embedding unsafe HTML (<script>, event handlers)
• More HTML = worse cross-platform compatibility — use in moderation
• 80% of content is fine with standard Markdown; HTML is for special needs only

📝 Exercises

1. Beginner: Write a Markdown paragraph where you use <span> to color one word red, and use <kbd> to display the "Ctrl+S" shortcut.

2. Intermediate: Create a custom-styled callout box (using <div> with background color and border) containing a paragraph and a link. Compare how it renders in VS Code vs. GitHub.

3. Challenge: Build an HTML table (with <thead> and <tbody>) that replaces a Markdown table, with a styled header row and a merged cell in the first row. Put both the HTML table and a Markdown table in the same document and compare their rendering.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us