fix(docs): preserve rendered entities and link query parameters

[rudycelekli]

Change

Decode renderer-owned HTML escapes exactly once before final output escaping. This restores visible table-of-contents characters and preserves link query parameters. Thanks @rudycelekli for the original repair.

The maintainer revision additionally fixes relative Markdown links with query strings: rewrite only the destination path, preserving the complete query/fragment suffix, and exclude those suffixes from filesystem link validation. It adds literal-entity, quote, angle-bracket and relative-link controls and reuses the shared builder fixture. This branch composes #939's complete hosted docs gate; land #939 first.

Verification

Head 82fce925fc555420b930808cb92a963db5b71b70, tree cbee447cef17083f9867f93f90ae2455b8095fbc. This supersedes d46daaff after integrating #939's synchronized parent and landed main through 155be083, with release notes grouped to avoid conflicts. The entity/link implementation and recorded proof source are unchanged; all eleven docs tests, lint and managed review passed again.

• Three generated-page cases fail against current main, with two source/control checks passing. The submitted candidate also exposed an unrewritten other.md?... relative destination; the additional path/suffix repair fixes it.
• All eleven docs-site tests pass, including inherited front-matter/hosted-gate controls. Docs lint, whitespace checks and managed scoped review pass.
• Four full production site builds each generate 70 HTML pages: base/candidate with the complete shipped docs, then base/candidate with two temporary links appended to the real index. No source inputs are modified.
• Independent Python standard-library HTML parsing consumes the actual emitted HTML, and WHATWG URLSearchParams consumes the decoded destinations. This is not merely matching encoded source strings.

Observed shipped-page TOC labels change from --focus-timeout <duration>, "Window not found" Error, and Prompt & Output to their intended visible characters. The added complete-site query probe changes from parameters q plus erroneous amp;format to q plus format. The relative probe additionally changes focus.md?...#focus-timeout-duration to focus.html?...#focus-timeout-duration. Source-module hashes and the complete input-document inventory remain stable across the final run.

This is generated-artifact/HTML-consumer proof, not live browser or desktop verification. Before/after browser screenshots remain unavailable: the integrated tool exposes no real Chrome connection, and the fallback extension route is not verified. No alternate browser profile, raw Chrome attachment, permission grant or shared browser configuration change was made. Fresh exact-head CI is also required before landing.

October 6 branch synchronization

Synchronized with current upstream main, preserving the maintainer revisions and the #939 → #931 → #940 landing order. Conflicts were resolved by retaining both the newly landed docs-metadata gate and the complete docs-site gate, and keeping all release notes. These are merge commits, so the previous source revisions and history remain intact.

Current signed/DCO head: 18148682b266b5a2b69dfde0569601af4258aec2. Relevant docs-site and docs-metadata tests: 15 passed; docs lint and whitespace checks passed. The production builder emitted 70 HTML pages on this revision. Earlier native/generated-artifact receipts remain historical evidence; no new live-browser screenshots or full Swift-suite run is claimed. Fresh hosted CI is pending.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[cursor]

PR Summary

Low Risk
Changes are limited to the documentation site renderer, tests, and CI gates; no runtime product, auth, or data paths are affected.

Overview
Fixes the static docs site builder so front matter parses on LF, CRLF, and mixed line endings without leaking YAML into the article body, and so TOC labels and link hrefs show the intended characters instead of double-escaped entities.

Adds decodeRenderedEntities and applies it once after structural HTML handling: TOC heading text is decoded after tag stripping; Markdown link destinations are decoded before path rewriting and final attribute escaping. rewriteHref and link validation now split path from ?/# suffixes so relative .md links keep query strings and fragments (e.g. other.html?q=one&format=json#section) and validators do not treat query parts as filesystem paths.

test:docs-site runs all tests/docs-site-*.test.mjs (shared fixture, front-matter cases, TOC/link regressions, workflow guard); macOS CI’s Docs lint step uses that script instead of only the TOC test. CHANGELOG and docs/building.md document the behavior and gate.

^{Reviewed by Cursor Bugbot for commit fa5a274. Bugbot is set up for automated code reviews on this repo. Configure here.}

[clawsweeper]

Codex review: needs changes before merge. Reviewed October 6, 2026, 2:43 AM ET / 06:43 UTC (Revision 5).

ClawSweeper review

What this changes

The branch repairs documentation heading text, preserves link queries and fragments, handles CRLF front matter, and shares generated-site regression coverage between local tests and CI.

Merge readiness

⛔ Needs changes before merge - 1 item remains

This PR remains necessary: current main and v4.8.0 retain the affected rendering behavior. No actionable correctness or security findings remain, and the recorded production-output proof is sufficient. The explicit prerequisite landing order still applies.

Priority: P2
Reviewed head: 18148682b266b5a2b69dfde0569601af4258aec2

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	A focused renderer repair has strong full-site artifact evidence, useful regression controls, and no actionable findings.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The production documentation builder was exercised over the complete site, and independent HTML and URL consumers observed corrected heading text and preserved external and relative-link parameters. The relevant production sources remain unchanged since that evidence; no stored-data contract changes.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The production documentation builder was exercised over the complete site, and independent HTML and URL consumers observed corrected heading text and preserved external and relative-link parameters. The relevant production sources remain unchanged since that evidence; no stored-data contract changes.
Evidence reviewed	7 items	Pinned introduced change: Read the complete introduced diff across all ten files. The production changes decode renderer escapes once, retain query and fragment suffixes during relative-link rewriting, normalize CRLF before metadata extraction, and update link validation. Regression fixtures, documentation, and the shared CI gate accompany these changes. Current main still needs the repair: Main returns escaped heading text without decoding it, then escapes it again when constructing the TOC. Its Markdown link renderer likewise escapes an already escaped destination; relative Markdown links with queries fail the .md suffix check. The latest release also retains the undecoded heading-text helper. Production artifact proof: The captured PR body records four complete production-site builds, each producing 70 HTML pages. Independent Python HTML parsing and WHATWG URLSearchParams observed corrected heading characters, q and format parameters instead of amp;format, and a relative focus.html destination retaining its query and fragment. This exercises emitted static output directly; browser screenshots are unnecessary for these demonstrated output transformations.
Findings	None	None.
Security	None	None.

How this fits together

Peekaboo’s documentation builder converts Markdown and page metadata into a static HTML site. Its heading extraction and link rewriting determine the navigation text and destinations readers receive.

flowchart TD
  A[Markdown and metadata] --> B[Documentation builder]
  B --> C[Rendered headings and links]
  C --> D[Decode renderer escapes once]
  D --> E[Preserve destination suffixes]
  E --> F[Escape final HTML]
  F --> G[Static documentation pages]

Loading

Before merge

• Complete next step (P2) - Land fix(docs): parse CRLF front matter before rendering #939 first, following the explicit ordering retained in the current PR body.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	production +19/-8; tests +122/-22	The small renderer repair is accompanied by generated-output controls and shared fixture coverage; counts include the composed front-matter prerequisite.

Technical review

Best possible solution:

Keep a single documentation renderer that preserves visible text and complete link destinations, with production-output regressions shared by local and hosted gates.

Do we have a high-confidence way to reproduce the issue?

Yes: current-main source establishes the double escaping and query-sensitive relative-link failure, and the captured production-build comparison records their observable output. This read-only review did not execute the builder.

Is this the best way to solve the issue?

Yes: decoding only renderer-owned escapes once, rewriting only the destination path, and escaping final output repair the existing contract without replacing the renderer.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 43b2fe2a7291.

Labels

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P2: This repairs documentation text and link destinations with a limited static-site blast radius.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The production documentation builder was exercised over the complete site, and independent HTML and URL consumers observed corrected heading text and preserved external and relative-link parameters. The relevant production sources remain unchanged since that evidence; no stored-data contract changes.
• proof: sufficient: Contributor real behavior proof is sufficient. The production documentation builder was exercised over the complete site, and independent HTML and URL consumers observed corrected heading text and preserved external and relative-link parameters. The relevant production sources remain unchanged since that evidence; no stored-data contract changes.

Evidence

What I checked:

• Pinned introduced change: Read the complete introduced diff across all ten files. The production changes decode renderer escapes once, retain query and fragment suffixes during relative-link rewriting, normalize CRLF before metadata extraction, and update link validation. Regression fixtures, documentation, and the shared CI gate accompany these changes. (scripts/build-docs-site.mjs:460, 18148682b266)
• Current main still needs the repair: Main returns escaped heading text without decoding it, then escapes it again when constructing the TOC. Its Markdown link renderer likewise escapes an already escaped destination; relative Markdown links with queries fail the .md suffix check. The latest release also retains the undecoded heading-text helper. (scripts/docs-site-toc.mjs:24, 4d43dc9d80cd)
• Production artifact proof: The captured PR body records four complete production-site builds, each producing 70 HTML pages. Independent Python HTML parsing and WHATWG URLSearchParams observed corrected heading characters, q and format parameters instead of amp;format, and a relative focus.html destination retaining its query and fragment. This exercises emitted static output directly; browser screenshots are unnecessary for these demonstrated output transformations. (82fce925fc55)
• Review continuity: GitHub comparison confirms the builder, entity helper, and docs-site regression files have no changes since the previous reviewed head. The prior review had no findings or rank-up moves. An initial local historical comparison failed because a promised blob was unavailable over HTTP 403; the read-only GitHub comparison resolved this specific coverage gap. (scripts/build-docs-site.mjs, 18148682b266)
• Explicit prerequisite remains open: The captured body and contributor follow-up retain the landing order fix(docs): parse CRLF front matter before rendering #939 before this PR, followed by fix(docs): assign unique heading permalink targets #940. A live read confirms the front-matter prerequisite is still open and unmerged. These are composed, distinct repairs rather than a merged replacement. (e258d59dcb80)
• Area history and routing: Current-main history repeatedly names Peter Steinberger for the documentation builder, including the original documentation hub and later structural heading extraction. Blame associates the helper’s first line with this commit, and GitHub verifies its author login as steipete; this supports routing without asserting causal responsibility. (scripts/docs-site-toc.mjs:1, 1cd64648f458)

Likely related people:

• Peter Steinberger: Raw commit 1cd6464 adds scripts/docs-site-toc.mjs:1 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 1cd64648f458; files: scripts/docs-site-toc.mjs)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (4 earlier review cycles)

• reviewed 2026-10-05T09:46:57.340Z sha 32b8417 :: needs real behavior proof before merge. :: none
• reviewed 2026-10-05T10:04:38.324Z sha 32b8417 :: needs maintainer review before merge. :: none
• reviewed 2026-10-05T12:45:10.136Z sha d46daaf :: needs changes before merge. :: none
• reviewed 2026-10-05T13:43:51.181Z sha 82fce92 :: needs changes before merge. :: none

[rudycelekli]

Synchronized this branch with current main at signed head 18148682b266b5a2b69dfde0569601af4258aec2 while preserving the maintainer revisions and landing order (#939, then #931, then #940). Relevant docs tests: 15 passing; docs lint/whitespace checks pass; the production builder emits 70 HTML pages. Details are in the updated body. Fresh CI remains pending; no new browser screenshot or full Swift suite is claimed.

@clawsweeper re-review

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/37425477701
• Updated: 2026-10-06T06:45:08.909Z

[steipete]

The owner consolidation is #992, combining the five related rendering repairs after independently reproducing them on current main. Its 24 renderer tests, metadata tests, lint, full site build, and P0–P2 review pass. It also includes actual Chrome before/after screenshots using identical synthetic input. This original will be closed as superseded once the combined candidate completes CI and lands; contributor credit is retained.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: fix(docs): preserve rendered entities and link query parameters This is item 1/1 in the current shard. Shard 0/1.

This temporary status tracks the active review worker. The completed review will appear in the durable ClawSweeper review comment.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[steipete]

Thanks for reporting the entity and query-string failures. Both were reproduced against main, and the verified repair plus regression coverage is consolidated in owner PR #992. I am closing this duplicate while #992 completes its remaining landing gates; this does not claim the fix is on main yet.