chore(docs): improve writing, add troubleshooting guide - #5409
Conversation
And a security overview
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 11 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (13)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe PR refreshes the Cheerio documentation, relocates extraction guidance, adds security and troubleshooting pages, updates navigation, and introduces lazy-loaded Sandpack editors for live examples. ChangesDocumentation and interactive examples
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Reader
participant LiveCode
participant SandpackEditor
participant Sandpack
Reader->>LiveCode: Click Edit & run
LiveCode->>SandpackEditor: Lazy-load editor
SandpackEditor->>Sandpack: Create Cheerio workspace
Reader->>SandpackEditor: Run or reset code
SandpackEditor->>Sandpack: Update /index.js or restore files
Sandpack-->>SandpackEditor: Console output or syntax errors
Reader->>LiveCode: Click Close
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
🟡 Changes recommended
The review found a couple of correctness/clarity issues in the updated docs/plugin behavior that should be fixed before merging.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
This PR updates the documentation site content and live-code UX: it rewrites several guides, adds new “Troubleshooting” and “Security” pages, moves the extract guide into Basics (with redirects), and changes the live-code rendering so readers see a static highlighted block until they opt into loading the Sandpack editor.
Changes:
- Add new docs pages for Selecting Elements, Extracting Data, Troubleshooting, and Security; refresh existing intro/basics/advanced writing.
- Update live-code remark/plugin + React components to preserve the highlighted code block as
LiveCodechildren and lazy-load Sandpack only when editing. - Pin Sandpack’s
cheeriodependency to the repo’s package version via a Vite-defined constant and add an Astro redirect for the movedextractpage.
File summaries
| File | Description |
|---|---|
| website/src/plugins/remark-live-code.ts | Wrap ```… live fences in LiveCode while preserving the code block as a child. |
| website/src/env.d.ts | Add a global TS declaration for __CHEERIO_VERSION__. |
| website/src/content/docs/intro.md | Rewrite introduction copy and restructure onboarding narrative. |
| website/src/content/docs/basics/troubleshooting.mdx | Add a new troubleshooting guide with live examples. |
| website/src/content/docs/basics/traversing.mdx | Rewrite traversal guide intro/outro and adjust section structure. |
| website/src/content/docs/basics/selecting.mdx | Add a new selecting guide (MDX + live examples). |
| website/src/content/docs/basics/selecting.md | Remove old selecting guide (replaced by MDX version). |
| website/src/content/docs/basics/manipulation.md | Rewrite manipulation guide prose and examples; add clarifications. |
| website/src/content/docs/basics/loading.md | Rewrite loading guide and expand fromURL behavior + request customization docs. |
| website/src/content/docs/basics/extract.mdx | Add extract guide under Basics with live examples. |
| website/src/content/docs/advanced/security.md | Add a new security overview page. |
| website/src/content/docs/advanced/extract.md | Remove old advanced extract page (moved to Basics). |
| website/src/content/docs/advanced/extending-cheerio.md | Rewrite/clarify extension points and TypeScript guidance. |
| website/src/content/docs/advanced/configuring-cheerio.md | Rewrite parser/configuration explanations and examples. |
| website/src/components/Sidebar.astro | Add new sidebar entries and move extract from Advanced to Basics; add Security. |
| website/src/components/sandpack-editor.tsx | New extracted Sandpack editor component with toolbar and dynamic sizing. |
| website/src/components/live-code.tsx | Lazy-load Sandpack editor and render a static highlighted block until editing. |
| website/astro.config.mjs | Define __CHEERIO_VERSION__ from root package.json; add redirect for moved extract. |
| src/api/manipulation.ts | Clarify empty() JSDoc to match behavior on non-container nodes. |
Review details
- Files reviewed: 18/19 changed files
- Comments generated: 2
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
| Supplying `requestOptions` discards the defaults entirely, so you must include | ||
| `method` yourself — omitting it fails with `method must be a string`. Custom | ||
| `headers` likewise replace the default `Accept` header rather than adding to it. |
| * see until they ask for an editor — no Sandpack, no third-party bundler, | ||
| * and it still renders without JavaScript. | ||
| */ | ||
| node.meta = null; |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
website/src/plugins/remark-live-code.ts (1)
29-53: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winPreserve code-fence metadata other than
live.Line 35 deletes all metadata. A fence such as
```js live {2} title="example.js"loses its title and line-highlight configuration before the normal code renderer processes the preserved child. Remove only the standalonelivemarker.Proposed fix
- node.meta = null; + node.meta = + node.meta?.replace(/(^|\s)live(?=\s|$)/, '$1').trim() || null;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/src/plugins/remark-live-code.ts` around lines 29 - 53, Update the metadata handling in the remark-live-code transformation to remove only the standalone live marker while preserving other fence metadata such as language, line highlighting, and title for the child code node. Replace the blanket assignment in the LiveCode wrapping logic without changing the existing code and JSX node behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/src/components/live-code.tsx`:
- Around line 41-50: Update the JSX in the LiveCode component so the “Edit &
run” button no longer uses absolute positioning over children. Place it in
normal document flow above the code block, preserving its existing styling and
click behavior.
In `@website/src/content/docs/advanced/configuring-cheerio.md`:
- Around line 133-141: Update the `.load()` example to define a valid markup
string and `htmlparser2` parser options before calling
`htmlparser2.parseDocument`; pass those defined values into `parseDocument` so
the example runs in Node and still demonstrates loading an already-parsed
document.
In `@website/src/content/docs/advanced/security.md`:
- Around line 29-33: Update the security guidance around scraped markup and
`text()` output to state that removing markup does not make untrusted text
universally safe. Instruct users to assign untrusted text through `textContent`
or escape it for the intended output context, while retaining the sanitizer
guidance for rendered markup.
- Around line 52-62: Update the “Selectors built from user input” documentation
to prohibit interpolating untrusted values even inside quoted attribute
selectors. Replace the interpolated-selector example with a fixed selector that
reads the attribute value and compares it as data, and retain guidance that user
input must not become selector syntax.
In `@website/src/content/docs/basics/manipulation.md`:
- Around line 103-107: Update the warning in the text() documentation to
describe prop('innerText') as tree-based extraction that omits script and style
content without applying CSS layout or visibility rules. Replace the
reader-visible wording while preserving the existing contrast with raw
textContent.
In `@website/src/content/docs/basics/troubleshooting.mdx`:
- Around line 138-144: Update the robust selector example to escape id according
to CSS string rules before interpolation, covering double quotes, backslashes,
and newlines; alternatively, avoid selector interpolation by selecting a broader
set and comparing the id attribute with .filter().
In `@website/src/content/docs/intro.md`:
- Around line 74-82: Update the DOM traversal example near the “Traversing the
DOM” section so the chained selector operates on markup that contains a matching
`.subtitle` descendant. Either add a `.subtitle` element under the existing
`h2.title` fixture and select its parent before calling `find()`, or change the
example selector to match the document loaded earlier, while preserving the
demonstration of traversal returning a match.
---
Outside diff comments:
In `@website/src/plugins/remark-live-code.ts`:
- Around line 29-53: Update the metadata handling in the remark-live-code
transformation to remove only the standalone live marker while preserving other
fence metadata such as language, line highlighting, and title for the child code
node. Replace the blanket assignment in the LiveCode wrapping logic without
changing the existing code and JSX node behavior.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: a00fcbf6-d020-40d4-b179-685501789036
📒 Files selected for processing (19)
src/api/manipulation.tswebsite/astro.config.mjswebsite/src/components/Sidebar.astrowebsite/src/components/live-code.tsxwebsite/src/components/sandpack-editor.tsxwebsite/src/content/docs/advanced/configuring-cheerio.mdwebsite/src/content/docs/advanced/extending-cheerio.mdwebsite/src/content/docs/advanced/extract.mdwebsite/src/content/docs/advanced/security.mdwebsite/src/content/docs/basics/extract.mdxwebsite/src/content/docs/basics/loading.mdwebsite/src/content/docs/basics/manipulation.mdwebsite/src/content/docs/basics/selecting.mdwebsite/src/content/docs/basics/selecting.mdxwebsite/src/content/docs/basics/traversing.mdxwebsite/src/content/docs/basics/troubleshooting.mdxwebsite/src/content/docs/intro.mdwebsite/src/env.d.tswebsite/src/plugins/remark-live-code.ts
💤 Files with no reviewable changes (2)
- website/src/content/docs/advanced/extract.md
- website/src/content/docs/basics/selecting.md
- Fix selector-injection advice in the security and troubleshooting
guides. Interpolating a value into a quoted attribute selector is not
safe: a `"` in the value closes the attribute and injects new selector
syntax. Recommend matching on a fixed selector and comparing the
attribute as data instead.
- Stop calling `text()` output safe. It strips markup structure but can
still contain `<`, `>` and `"`, which rebuild markup in an HTML sink.
- Correct `prop('innerText')`: it skips script and style content, but
applies no CSS, so `display: none` content is still included.
- Derive the sidebar and the prev/next pager from one shared module.
The two lists had drifted, leaving the new pages with no pagination
and a dead link to the old extract URL.
- Add an error boundary around the lazily loaded editor, so a failed
chunk falls back to the static code block instead of unmounting it.
- Move the "Edit & run" button out of the code block's top-right corner,
where it could cover a long line, into a bar above it.
- Note that some browser-only pseudo-classes throw rather than matching
nothing, and soften the claim about css-select's pseudo-class support.
- Make the intro `find()` example and the htmlparser2 `parseDocument`
example actually runnable.
- Document `requestOptions` precisely: `headers` is overridden only when
supplied, but `method` is never defaulted.
- Strip only the `live` token from code fence meta, not all of it.
There was a problem hiding this comment.
🟡 Changes recommended
The new redirect only covers /docs/advanced/extract and should also redirect /docs/advanced/extract/ to avoid breaking existing trailing-slash links.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
Suppressed comments (1)
website/astro.config.mjs:29
- The redirect keeps the old
advanced/extractURL working, but it only covers the no-trailing-slash form. The docs navigation and canonical links use trailing slashes (e.g./docs/advanced/extract/), so existing inbound links may still 404 unless that variant is redirected too.
// `extract` moved from Advanced to Basics; keep the published URL working.
redirects: {
'/docs/advanced/extract': '/docs/basics/extract/',
},
- Files reviewed: 20/21 changed files
- Comments generated: 0 new
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
There was a problem hiding this comment.
🟡 Changes recommended
The new redirect for the moved Extract page likely misses the trailing-slash URL that was previously published and may cause a 404 for existing links.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
Suppressed comments (1)
website/astro.config.mjs:29
- The redirect keeps
/docs/advanced/extractworking, but the previously published sidebar URL used a trailing slash (/docs/advanced/extract/). With the current config, that variant may not redirect and could 404 depending on Astro’s route normalization/trailing-slash settings. Add an explicit redirect for the trailing-slash path as well.
// `extract` moved from Advanced to Basics; keep the published URL working.
redirects: {
'/docs/advanced/extract': '/docs/basics/extract/',
},
- Files reviewed: 20/21 changed files
- Comments generated: 0 new
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
And a security overview