Skip to content

MD033 - No HTML tags

Aliases: no-inline-html

What this rule does

Prevents the use of HTML tags in Markdown - use Markdown syntax instead.

Why this matters

  • Portability: Pure Markdown works everywhere, HTML might be blocked or stripped
  • Security: Many platforms sanitize HTML for security reasons
  • Simplicity: Markdown syntax is cleaner and easier to read than HTML
  • Consistency: Mixing HTML and Markdown creates inconsistent documents

Examples

✅ Correct

# Heading

This is a paragraph with **bold** and *italic* text.

> This is a quote

- List item 1
- List item 2

[Link text](https://example.com)

![Image description](image.png)

Contact us at <[email protected]>
Visit <https://example.com>

❌ Incorrect

# Heading

This is a paragraph with <strong>bold</strong> and <em>italic</em> text.

<blockquote>This is a quote</blockquote>

<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

<a href="https://example.com">Link text</a>

<img src="image.png" alt="Image description">

🔧 Fixed

# Heading

This is a paragraph with **bold** and *italic* text.

> This is a quote

- List item 1
- List item 2

[Link text](https://example.com)

![Image description](image.png)

Configuration

[MD033]
allowed-elements = []     # List of allowed HTML tags (default: none)
disallowed-elements = []  # List of disallowed HTML tags (enables disallowed-only mode)

Shorthand aliases are also supported:

[MD033]
allowed = []              # Alias for allowed-elements
disallowed = []           # Alias for disallowed-elements

Example allowing specific tags

[MD033]
allowed-elements = ["br", "hr", "details", "summary"]

This would allow line breaks, horizontal rules, and collapsible sections while blocking other HTML.

GFM Security Mode (disallowed-only)

For GitHub Flavored Markdown, you can use the disallowed-elements option to only flag security-sensitive HTML tags while allowing all other HTML. Use the special value "gfm" to automatically include all GFM-disallowed tags:

[MD033]
disallowed-elements = ["gfm"]

This flags only these security-sensitive tags:

  • <title>, <textarea>, <style>, <xmp>, <iframe>
  • <noembed>, <noframes>, <script>, <plaintext>

These are the same tags that GitHub filters from rendered markdown for security reasons.

Custom disallowed tags

You can also specify your own list of disallowed tags:

[MD033]
disallowed-elements = ["script", "iframe", "style"]

Or combine GFM tags with custom ones:

[MD033]
disallowed-elements = ["gfm", "marquee", "blink"]

mdbook projects with semantic HTML

mdbook documentation often uses HTML with CSS classes to add semantic meaning that pure Markdown cannot express (e.g., marking text as filenames, captions, or warnings). For mdbook projects, you can allow semantic containers:

[tool.rumdl.MD033]
allowed-elements = ["div", "span"]

This permits semantic HTML like:

  • <span class="filename">src/main.rs</span> - Filename styling
  • <div class="warning">Important note</div> - Warning boxes
  • <span class="caption">Figure 1: Architecture</span> - Figure captions

While still catching potentially problematic HTML like <em>, <strong>, or <script> tags that have Markdown equivalents or security concerns.

Automatic fixes

This rule can automatically remove HTML tags when no allowed elements are configured. When specific tags are allowed via allowed_elements, those tags will be preserved while others are removed.

Note: The automatic fix removes HTML tags but does not convert them to Markdown equivalents. You may need to manually add appropriate Markdown formatting after the fix.

What's allowed

These are not considered HTML and are allowed:

  • HTML comments: <!-- This is a comment -->
  • Email autolinks: <[email protected]>
  • URL autolinks: <https://example.com>
  • FTP autolinks: <ftp://files.example.com>

Learn more

  • MD046 - Code block style should be consistent
  • MD034 - URLs should be formatted as links