markdownlint "MD033/no-inline-html" error
Fixes markdownlint MD033 violations from inline HTML in markdown docs. The skill shows how to replace inline HTML with markdown equivalents, allowlist the specific elements the project needs, and handle the kbd, details, and img cases. It keeps docs portable across renderers.
TL;DR
Replace inline HTML with markdown where possible; where HTML is required (details/summary, kbd), add those elements to the MD033 allowed_elements list. Rerun markdownlint to confirm.
The exact error
MD033/no-inline-html: Inline HTML [Element: kbd]Steps
Find the violations Run markdownlint and collect MD033 hits with the flagged element names. Success check: You have the list of inline HTML elements per file.
Replace with markdown Convert simple cases: b and i to bold/italic, br to line breaks, img to markdown image syntax where the renderer supports it. Success check: As much inline HTML as possible is now pure markdown.
Allowlist the rest For elements markdown cannot express (details, summary, kbd), add them to allowed_elements in the MD033 config. Success check: The config allowlists exactly the elements the docs need.
Rerun the linter Run markdownlint and confirm zero MD033 violations. Success check: Clean run with the allowlist in place.
When to use
- Use when markdownlint flags inline HTML in docs.
- Use when an agent writes docs for renderers with limited HTML support.
When not to use
- Not for MD013 line length (different rule).
- Not for HTML that must stay for email rendering (allowlist and move on).
Why it happens
MD033 exists because inline HTML renders inconsistently across markdown processors. Docs that target multiple renderers (GitHub, Docusaurus, mkdocs) break subtly when they lean on raw HTML.
Edge cases
The allowed_elements option is the intended escape hatch, not a cheat; documenting why each element is needed keeps the list honest. Some static site generators strip unknown HTML at build time, which makes MD033 a correctness gate, not just style.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_OW7drHEbvCt4h7QJ-qfL2w