markdownlint "MD033/no-inline-html" in CI

By Daniel Zoghalchali·Latchkey

markdownlint rule MD033 forbids raw HTML inside Markdown. It reports the element name it found and exits non-zero. Docs often need HTML (details, br, img with attributes), so this fires on intentional markup.

What this error means

markdownlint fails with "MD033/no-inline-html Inline HTML [Element: div]" (or br, details, img, kbd) on lines that use raw tags.

docs/faq.md:22 MD033/no-inline-html Inline HTML [Element: details]
docs/faq.md:31 MD033/no-inline-html Inline HTML [Element: br]

Common causes

Intentional HTML the docs need

Collapsible <details>, <br> line breaks, <kbd> keys, or <img> with width attributes are valid HTML that MD033 blocks by default.

The rule is on with no allowlist

Default MD033 allows no elements, so every raw tag is an error until you list the ones you use.

How to fix it

Allow the specific elements you use

1. List the HTML elements your docs legitimately need.
2. Add them to allowed_elements under MD033.
3. Commit the config so CI accepts exactly those tags.

{
  "MD033": {
    "allowed_elements": ["details", "summary", "br", "kbd", "img"]
  }
}

Disable MD033 with an inline comment where unavoidable

For a one-off block, wrap it in markdownlint disable/enable comments instead of turning the rule off globally.

<!-- markdownlint-disable MD033 -->
<div class="grid">...</div>
<!-- markdownlint-enable MD033 -->

How to prevent it

• Maintain an allowed_elements list for the HTML your docs use.
• Prefer Markdown syntax over raw HTML where equivalent exists.
• Use scoped disable comments rather than disabling MD033 repo-wide.

Frequently asked questions

Related guides

References

• GitHub Actions documentation