fix(cli): skip backtick code spans in docs sanitizer - #9334
Conversation
The docs generator (`packages/cli/docsgen/markdown.ts`) HTML-encodes `{` and `}`
to `&ChainSafe#123;` / `&ChainSafe#125;` globally — even inside backtick code spans, where the
encoded entities render verbatim instead of being decoded back. As a result,
the docs page for `--serveHistoricalState` showed `&ChainSafe#123;state_id&ChainSafe#125;`
instead of `{state_id}` for the example URL.
Sidestepping the issue by using `head` (a real, valid `state_id` value)
in the example. The underlying sanitizer bug should be fixed separately so
descriptions can use placeholder syntax without surprises.
🤖 Generated with AI assistance
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the description for the serveHistoricalState CLI option in packages/cli/src/options/beaconNodeOptions/chain.ts, changing the example REST API endpoint from using a generic {state_id} placeholder to head. I have no feedback to provide as there were no review comments to evaluate.
nflaig
changed the title
| serveHistoricalState: { | ||
| description: | ||
| "Regenerate finalized beacon states on demand and serve them via the REST API (e.g. `/eth/v2/debug/beacon/states/{state_id}`). \ | ||
| "Regenerate finalized beacon states on demand and serve them via the REST API (e.g. `/eth/v2/debug/beacon/states/head`). \ |
There was a problem hiding this comment.
head is probably the worst example value you could have chosen here, can we escape the {?
There was a problem hiding this comment.
Good call. Switched to {state_id} — the HTML entity passes through sanitizeDescription() unchanged (it only replaces literal {/}) and renders as {state_id} on the docs page.
Replace `head` with `&ChainSafe#123;state_id&ChainSafe#125;` so sanitizeDescription() passes it through unchanged — the HTML entity renders as `{state_id}` on the docs page without triggering the replaceAll("{") → &ChainSafe#123; substitution. 🤖 Generated with AI assistance
| serveHistoricalState: { | ||
| description: | ||
| "Regenerate finalized beacon states on demand and serve them via the REST API (e.g. `/eth/v2/debug/beacon/states/{state_id}`). \ | ||
| "Regenerate finalized beacon states on demand and serve them via the REST API (e.g. `/eth/v2/debug/beacon/states/{state_id}`). \ |
There was a problem hiding this comment.
how does {state_id} render if you run --help? we should account for that too
There was a problem hiding this comment.
You're right — the entity wouldn't decode in --help (yargs prints the description string verbatim, no HTML rendering), so users would see literal {state_id} in the terminal. Bad fix.
Fixed properly in 1c4b5e8: updated sanitizeDescription() in packages/cli/docsgen/markdown.ts to skip content inside backtick code spans, and reverted the description back to {state_id} (literal). Now:
--help: shows{state_id}✓- Docs page: sanitizer leaves backtick content alone, MDX renders inline code as literal text →
{state_id}✓
Updated PR scope from "swap placeholder workaround" to "fix the sanitizer properly" — the underlying bug I called out in the original PR description. Will update the PR title/body to match.
The docs sanitizer was HTML-encoding `{`, `}`, `<`, `>` globally — including
inside backtick code spans. Markdown code spans render their contents as literal
text and do not decode HTML entities, so encoded entities surfaced on the docs
page (e.g. users saw `&ChainSafe#123;state_id&ChainSafe#125;` instead of `{state_id}`).
Fix: skip content inside backtick code spans during sanitization. MDX (the docs
renderer) also treats inline code as literal, so braces inside backticks don't
need escaping there.
Reverts the `&ChainSafe#123;state_id&ChainSafe#125;` workaround in `--serveHistoricalState` back
to the literal `{state_id}` placeholder, which now renders correctly in both
`--help` (terminal) and on the docs page.
Addresses Nico's review comment on PR ChainSafe#9334 (`&ChainSafe#123;state_id&ChainSafe#125;` would show
literally in `--help` output).
🤖 Generated with AI assistance
lodekeeper
changed the title
2 participants
Summary
Fix the broken docs render for the
--serveHistoricalStatehelp text on the docs site (reported in PR #9328). Replaces{state_id}withheadin the example URL.Root cause
packages/cli/docsgen/markdown.ts:7sanitizeDescription()HTML-encodes{→{and}→}globally — including text inside backtick code spans. Markdown code spans render their contents as literal text, so the encoded entities never decode back to{and}— users see{state_id}verbatim on the docs page.This is the only
{...}placeholder I added in #9328. Sidestepping by usinghead, which is a validstate_idvalue (the user can substitute any other real value:genesis,finalized,<slot>, etc.).Follow-up
The
sanitizeDescriptionfunction should be fixed properly so future descriptions can use{...}placeholders (and<...>placeholders) without breaking docs rendering. Filing this as a separate concern — out of scope for this hot-fix.Test plan
chain.ts.serveHistoricalStatehelp text without HTML entity codes.🤖 Generated with Claude Code