## 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
```text
MD033/no-inline-html: Inline HTML [Element: kbd]
```

## Steps
1. **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.
2. **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.
3. **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.
4. **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