docs agent's markdown renderer escaped html entities in code samples
Fixes docs pipelines where the Markdown renderer double-escapes HTML entities inside code samples. Use when code samples show entities like and symbols instead of the intended characters. Not for MDX tag errors.
TL;DR
Render code blocks verbatim: disable HTML-entity escaping inside fenced code, or stop pre-escaping content before handing it to the renderer. Escaping twice is the entire bug.
Error
(code sample renders entities like and-lt-semicolon instead of the intended characters; entities visible to readers)Steps
- Confirm the double escape: view the page source and look for doubly-escaped entity sequences (the letters "amp" appearing inside an entity), which mean the content was escaped twice. Expected: double-escaped entities confirmed.
- Find which stage escapes: the agent's template, a sanitizer, or the Markdown renderer options. Feed a raw sample through each stage. Expected: the escaping stage identified.
- Ensure exactly one stage escapes, and that the Markdown renderer treats fenced code as verbatim (most do by default; custom renderers may not). Expected: single escaping, verbatim code blocks.
- Re-render and check the samples display the intended characters. Expected: code samples read correctly.
When to use
- Code samples display HTML entities instead of characters
- Page source shows doubly-escaped sequences
- A docs agent pre-processes Markdown before rendering
When not to use
- Entities appear in prose (single escaping may be correct there)
- The renderer is MDX (check component escaping rules instead)
- The source Markdown itself contains the entities (fix the source)
Tool compatibility
Any Markdown renderer in a docs pipeline (Python markdown, marked, remark). The double-escape pattern is renderer-independent.
Variant phrasings
entities escaped in headings but not code
The escaping stage runs before parsing and does not respect code context. Move escaping after parsing or scope it to prose.
only agent-generated pages are affected
The agent's output template escapes; hand-written pages bypass it. Fix the template.
Why it happens
Pipelines often sanitize agent output and then render it, with both stages escaping HTML. Each stage is correct alone; together they produce visible entities.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_MpBvKrSH7SIffOJ0dQX0xw