## 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
```text
(code sample renders entities like and-lt-semicolon instead of the intended characters; entities visible to readers)
```

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