Can I Use HTML in Markdown Documents?

When Simplicity Meets Flexibility

Markdown's elegant simplicity handles 95% of content formatting needs—headings, lists, links, emphasis, code. But occasionally you encounter requirements Markdown cannot address: custom styling, complex layouts, embedded videos, or precise spacing control. This is where Markdown's HTML compatibility becomes invaluable. Most Markdown parsers allow inline HTML, enabling you to leverage HTML's full power when Markdown's limitations become constraints.

However, this flexibility comes with important caveats: security restrictions on some platforms, reduced portability, and complexity that undermines Markdown's core philosophy. Understanding when HTML enhances Markdown versus when it betrays its purpose is crucial for effective documentation.

The Short Answer: Usually Yes

Most Markdown parsers support inline HTML, treating it as a first-class citizen within Markdown documents. You can freely mix HTML tags with Markdown syntax, and parsers will render both appropriately.

Basic HTML Integration

## Markdown Heading

This is regular Markdown with **bold text**.

<div class="custom-alert">
  This is an HTML div with custom classes.
</div>

Back to *Markdown* content.

The HTML <div> renders normally, surrounded by Markdown content. Simple and powerful.

Why Markdown Allows HTML

Historical Design Decision: John Gruber designed Markdown explicitly for "writing for the web"—his original specification states: "Markdown is not a replacement for HTML, or even close to it... The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. But if you want to add HTML, you can."

Practical Necessity: No lightweight markup language can cover every use case without becoming as complex as HTML itself. Rather than attempt completeness, Markdown provides an escape hatch for edge cases.

Web Target: Since Markdown typically converts to HTML for web display, allowing HTML input makes sense—it's the native target format anyway.

Common Use Cases for HTML in Markdown

1. Custom Styling with Classes and IDs

Markdown has no syntax for CSS classes or IDs. HTML provides access:

<div class="alert alert-warning">
  **Warning**: This action cannot be undone.
</div>

<p id="important-note" class="highlight">
  Remember to save your work frequently.
</p>

Use Case: Documentation sites with theme-specific alert boxes, callouts, or styled components.

2. Images with Specific Dimensions

Markdown's image syntax is simple:

![Alt text](image.jpg)

But it doesn't support width/height. HTML does:

<img src="image.jpg" alt="Alt text" width="300" height="200">

Or with modern responsive techniques:

<img src="image.jpg" alt="Alt text" style="max-width: 100%; height: auto;">

3. Embedded Videos and iframes

Markdown has no video or iframe syntax. HTML is required:

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  frameborder="0"
  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen>
</iframe>

Common Embeddings: YouTube videos, Twitter posts, CodePen demos, Google Maps.

4. Complex Tables

While Markdown supports basic tables (GFM), complex requirements need HTML:

Merged Cells:

<table>
  <tr>
    <th rowspan="2">Feature</th>
    <th colspan="2">Availability</th>
  </tr>
  <tr>
    <th>Free</th>
    <th>Pro</th>
  </tr>
  <tr>
    <td>Storage</td>
    <td>10 GB</td>
    <td>100 GB</td>
  </tr>
</table>

Custom Styling:

<table class="comparison-table">
  <tr class="header-row">
    <th>Feature</th>
    <th class="highlight">Pro Plan</th>
  </tr>
</table>

5. Definition Lists

Markdown doesn't have native definition list syntax (though some extensions add it):

<dl>
  <dt>API</dt>
  <dd>Application Programming Interface - a set of protocols for building software applications.</dd>

  <dt>REST</dt>
  <dd>Representational State Transfer - an architectural style for web services.</dd>
</dl>

6. Precise Spacing and Layout Control

Markdown whitespace collapses. HTML provides control:

Line Breaks:

First line<br>
Second line<br>
Third line

Non-Breaking Spaces:

Price:&nbsp;$99.99

Margins and Padding:

<div style="margin-top: 40px; padding: 20px;">
  Content with specific spacing
</div>

7. Details/Summary (Collapsible Sections)

Markdown lacks collapsible content syntax:

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

  This content is initially hidden and expands when clicked.

  - Can include any Markdown content
  - Lists, code, links, etc.
</details>

Note: Markdown inside <details> may not render on all platforms—test your target environment.

8. Superscript and Subscript

Scientific and mathematical notation often requires:

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

Renders as: E = mc² and H₂O

9. Keyboard Input and Sample Output

Semantic HTML for technical documentation:

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.
The command output is <samp>Success: 100% complete</samp>.

10. Custom Attributes and Data

For JavaScript interactions or data attributes:

<div data-tool-id="123" data-category="security" onclick="showDetails(this)">
  Click for more information
</div>

Platform-Specific HTML Support

Not all Markdown platforms allow unrestricted HTML:

GitHub (GitHub Flavored Markdown)

Supported: Most HTML tags work in README files, issues, pull requests, comments.

Restricted for Security: GitHub filters dangerous tags and attributes:

Blocked: <script>, <style> (inline), <iframe> (except whitelisted), event handlers (onclick, etc.)
Allowed: <div>, <span>, <table>, <img>, <br>, <details>, most structural and semantic tags

Example: <img> works, but <iframe> for external embeds doesn't (except YouTube, Vimeo, etc. on specific whitelist).

Static Site Generators (Jekyll, Hugo, Gatsby)

Full Support: Since they control the entire build process, static site generators generally allow unrestricted HTML in Markdown files. The HTML passes through to final output.

Configuration: Some generators let you disable HTML for security if accepting untrusted content.

Stack Overflow and Reddit

Limited Support: These platforms support some HTML tags but filter heavily for security:

Basic formatting: <b>, <i>, <code>, <pre>
Links: <a> (with restrictions)
Blocked: Most structural tags, all scripting, embedded content

Notion, Obsidian, Note-Taking Apps

Varies Widely:

Notion: Limited HTML support; focuses on native block types
Obsidian: Full HTML support in reading mode
Bear: Limited HTML tags
Typora: Good HTML support

Always test in your target platform.

Content Management Systems

WordPress, Ghost, Medium:

WordPress: HTML allowed in posts (user permissions-dependent)
Ghost: Markdown with HTML support
Medium: Limited—prefers Medium's native formatting

Documentation Platforms

Read the Docs, GitBook, MkDocs:

Generally support HTML within reason
May filter scripts and risky tags
Check specific platform documentation

Best Practices for Mixing HTML and Markdown

1. Use HTML Sparingly

Principle: Markdown first, HTML when necessary.

Excessive HTML undermines Markdown's readability. This defeats the purpose:

<h2>My Heading</h2>

<p>This is a <strong>paragraph</strong> with <em>emphasis</em>.</p>

<ul>
  <li>First item</li>
  <li>Second item</li>
</ul>

Much better:

## My Heading

This is a **paragraph** with *emphasis*.

- First item
- Second item

2. Isolate HTML Blocks

Keep HTML blocks separate from inline Markdown for cleaner parsing:

Problematic Mixing:

<div class="alert">
This **bold text** might not render correctly.
</div>

Better Separation:

<div class="alert">

This **bold text** renders correctly because of blank lines.

</div>

Or use HTML throughout the block:

<div class="alert">
  This <strong>bold text</strong> definitely works.
</div>

3. Comment Your HTML

HTML in Markdown is less self-evident than Markdown syntax. Add comments:

<!-- Alert box for important warnings -->
<div class="alert alert-danger">
  **Warning**: Permanent action ahead.
</div>

<!-- End alert -->

4. Consider Portability

HTML reduces portability. Content with extensive HTML won't convert cleanly to non-HTML formats (PDF, Word, plain text) via Pandoc or similar tools.

If portability matters: Minimize HTML usage or use platform-specific shortcodes/extensions that provide HTML-like functionality while maintaining Markdown format.

5. Validate Accessibility

Custom HTML requires manual accessibility attention:

Add alt text to all images
Use semantic HTML (<nav>, <article>, <aside>)
Ensure sufficient color contrast
Test with screen readers
Provide keyboard navigation for interactive elements

Markdown converters often handle basic accessibility; custom HTML is your responsibility.

6. Test Cross-Platform

If your Markdown appears on multiple platforms, test HTML rendering everywhere:

GitHub vs. GitLab rendering differences
Static site generation output
Documentation platform rendering
Mobile display
Different browser rendering

7. Document Custom Styles

If using custom CSS classes, document them:

<!-- Available custom classes: -->
<!-- .alert-info, .alert-warning, .alert-danger -->
<!-- .code-example, .terminal-output -->

<div class="alert-warning">
  Important information here.
</div>

Or maintain a style guide.

Security Considerations

XSS (Cross-Site Scripting) Risks

If your Markdown accepts user input, unrestricted HTML creates XSS vulnerabilities:

Dangerous:

<script>
  // Malicious code could be injected
  stealUserData();
</script>

<img src="x" onerror="maliciousCode()">

Mitigation:

Use markdown parsers with sanitization (marked, markdown-it with plugins)
Whitelist allowed HTML tags
Strip or escape dangerous attributes (onclick, onerror, etc.)
Never trust user-submitted HTML

Content Security Policy

Implement CSP headers to prevent inline script execution even if HTML bypasses filters.

The Markdown-HTML Balance

HTML in Markdown is a powerful escape hatch but also a double-edged sword. It solves limitations and enables advanced features—at the cost of simplicity, portability, and maintainability. The art lies in finding the balance: using Markdown's clean syntax for 95% of content while judiciously applying HTML only when Markdown genuinely cannot meet requirements.

Preview Your Hybrid Documents

Want to see how HTML renders within your Markdown? Our Markdown Preview tool supports HTML within Markdown, letting you test complex layouts and ensure cross-platform compatibility. Perfect for validating that your custom HTML works as intended.

Expanding Possibilities, Respecting Constraints

HTML compatibility makes Markdown remarkably flexible—no longer limited to simple formatting, Markdown becomes a gateway to the full expressiveness of web technologies. Yet with this power comes responsibility: every <div> and <style> tag moves further from Markdown's foundational principle of readable, portable plain text.

Use HTML when needed. Respect Markdown's simplicity when sufficient. The most effective documentation balances both, leveraging each technology's strengths while avoiding their pitfalls. Master this balance, and you'll create content that's simultaneously powerful, maintainable, and accessible—the true promise of modern technical writing.