feat(docs): add "was this page helpful?" feedback widget to docs pages - #507
Conversation
A thumbs-up / thumbs-down vote below the page content on every docs page,
captured to PostHog as `docs_feedback` with `{ helpful, page }`.
It renders from Footer.astro's sidebar (doc-page) branch rather than a
per-page import or frontmatter flag — the same indirection the Cloud CTA
already uses — so every content page gets it automatically, including
pages not written yet. It sits below the Cloud CTA on the pages that
carry one, and above the edit-link / prev-next chrome. Splash pages (the
homepage and 404) take the other footer branch and never render it.
One vote per page per visitor: the choice is remembered in localStorage
keyed by pathname, and a revisit renders the thanks message instead of
re-prompting. Storage is a nicety, not the record — the capture is what
counts, so a browser with storage disabled still votes.
The widget owns no outer spacing or rule: as a grid item of
.wh-footer--compact it inherits that footer's gap, which is what keeps it
aligned with the Cloud CTA above and the edit-link row below.
Follows the codebase's DOM-script convention (is:inline, IIFE, window
init flag, one delegated click listener, re-render on both
DOMContentLoaded and astro:page-load) so it survives view transitions,
and the --wh-* design tokens so it follows the site theme in light and
dark.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
documentation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📜 Recent review details🔇 Additional comments (2)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdded a documentation feedback widget with thumbs-up/down voting, PostHog event capture, pathname-based localStorage persistence, navigation restoration, and a confirmation state. The widget renders in the compact footer except on 404 pages. ChangesDocumentation feedback
Estimated code review effort: 3 (Moderate) | ~20 minutes Merge Risk: 🟡 Moderate · up to The widget can mark a vote as completed even when the feedback event is not delivered, causing lost page feedback and preventing a visitor from retrying; the selected choice is also not exposed to assistive technology. Merge should wait for these issues to be addressed or explicitly accepted. Suggested reviewers: Sequence Diagram(s)sequenceDiagram
participant Visitor
participant PageFeedback
participant localStorage
participant PostHog
Visitor->>PageFeedback: Select thumbs-up or thumbs-down
PageFeedback->>PostHog: Capture docs_feedback event
PageFeedback->>localStorage: Store vote for pathname
PageFeedback->>Visitor: Show confirmation state
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: bf42c32e-b828-43b9-bee2-8a682c2193c7
📒 Files selected for processing (3)
CHANGELOG.mddocs/src/components/Footer.astrodocs/src/components/PageFeedback.astro
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Analyze (go)
- GitHub Check: Analyze (go)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
- Never hard-wrap prose. One paragraph is one line. No wrapping at 72/80 columns, no "semantic linefeeds" splitting a paragraph at sentence boundaries.
Files:
CHANGELOG.md
🔇 Additional comments (5)
docs/src/components/PageFeedback.astro (2)
18-56: LGTM!
139-159: 📐 Maintainability & Code QualityNo additional
:focus-visiblestyle is required.docs/src/styles/global.cssalready applies a visible focus outline to all focusable elements, including these vote buttons.> Likely an incorrect or invalid review comment.CHANGELOG.md (1)
11-14: LGTM!docs/src/components/Footer.astro (2)
19-19: LGTM!Also applies to: 67-67
46-51: 🩺 Stability & AvailabilityKeep the direct
entry.idaccess. Starlight definesentryas required andentry.idas a non-nullable string, including the 404 fallback entry.> Likely an incorrect or invalid review comment.
github-project-automation
Bot
moved this from Backlog
to In review
in WaveHouse Task Board
|
📚 Docs preview is live → https://a4270e22-wavehouse-docs.wave-rf.workers.dev |
If PostHog is blocked (ad blocker, consent banner, still loading), the capture is a no-op — but rememberVote() ran anyway, locking the visitor out of ever voting again with the event lost. Gate persistence on typeof capture === 'function' so the visitor is re-prompted instead.
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: fd69c41a-b3c1-4c74-b343-f4dcec63c023
📒 Files selected for processing (1)
docs/src/components/PageFeedback.astro
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: Docs build
- GitHub Check: Lint
- GitHub Check: Analyze (go)
- GitHub Check: Analyze (go)
🔇 Additional comments (1)
docs/src/components/PageFeedback.astro (1)
2-24: LGTM!Also applies to: 27-56, 119-187
There was a problem hiding this comment.
My thoughts:
- We should let them still see their feedback/change it after clicking – right now I have no way to see what I clicked or change my vote
- It should send the vote with the current build id or commit sha or something, so we can pin down the version of the docs they liked or didn't like at that point in time
- Similarly, if the docs change either on that page or generally or its a new commit sha or build id or whatever, let them re-vote (ie clear their last vote from localstorage/don't show it again)
- I think the styling of the page needs to change, it looks weird in its current form. Maybe centered and less prominent/better matching the secondary colors/fonts, or remove the edit page link and put this where that was instead or something, replacing it with a link to open an issue or something if their adblocker or whatever isn't letting it load?
…xpiry Address Eric's review: - After voting, the chosen thumb stays highlighted and the other remains clickable to change the vote (fires a new capture with changed: true). - Each capture includes the build SHA so feedback ties to a specific docs revision. - Votes are scoped to the build SHA in localStorage; a new build clears stale votes so visitors can re-evaluate updated content. - Centered, smaller, muted-color styling — less prominent than content.
Clicking the active thumb toggles it off — clears localStorage and fires a docs_feedback capture with retracted: true and helpful: null so PostHog can distinguish retractions from votes. The widget returns to the prompt state.
There was a problem hiding this comment.
Actionable comments posted: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: dc040461-f608-4792-a42d-c613eef4046b
📒 Files selected for processing (1)
docs/src/components/PageFeedback.astro
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout. (5)
- GitHub Check: Docs build
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: Analyze (go)
- GitHub Check: Lint
- GitHub Check: Analyze (go)
🔇 Additional comments (1)
docs/src/components/PageFeedback.astro (1)
145-150: PostHog readiness remains unresolved.A
capturefunction can be the PostHog loader stub. Its presence does not confirm that the queued event will be delivered before this code persists the vote.
… clearing - aria-pressed synced on render, vote, change-vote, and retract so screen readers can identify the selected thumb. - localStorage.removeItem moved outside the PostHog capture guard in the retract path — if PostHog is blocked but a prior vote exists, the retract still clears storage so the visitor can re-vote on reload.
|
@coderabbitai review |
✅ Action performedReview finished.
|
github-project-automation
Bot
moved this from In review
to In progress
in WaveHouse Task Board
github-project-automation
Bot
moved this from In progress
to Done
in WaveHouse Task Board
2 participants
Summary
Adds a "Was this page helpful?" thumbs-up / thumbs-down widget below the content of every docs page, so we get a per-page signal on which pages actually land.
window.posthog?.capture('docs_feedback', { helpful, page })—helpfulistrue/false,pageislocation.pathname(belt-and-braces; PostHog derives pathname itself). Guarded with?.like every other capture on the site;PostHog.astrois untouched.localStoragekeyed by pathname, and a revisit renders the thanks message instead of re-prompting. Storage is a nicety, not the record — the capture is what counts, so a browser with storage disabled still votes (it just gets asked again).Footer.astro's sidebar (doc-page) branch — the same indirection the Cloud CTA already uses — not from a per-page import or frontmatter flag. A new page underdocs/src/content/docs/gets the widget on its first build with zero authoring work..wh-footer--compactit inherits that footer'sgap, which is what keeps it aligned with the CTA above and the edit-link row below.template: splash, so they take the other footer branch and never render it. An explicit 404 id check keeps that true if the 404 page ever stops being a splash page.Accessibility and theming follow the surrounding components: real
<button>s witharia-labels, keyboard operable, the site's global:focus-visiblering, arole="status"thanks message that receives focus after a vote (the pressed button isdisplay:noneby then), and--wh-*design tokens throughout so it follows the theme in light and dark. The script uses the codebase's DOM-script convention (is:inline, IIFE,windowinit flag, one delegated click listener, re-render on bothDOMContentLoadedandastro:page-load) so it survives view transitions without accumulating listeners.The
Footer.astrodiff is 9 added lines in three hunks (import, oneconst, one JSX line), deliberately kept clear of the<DocsTracking />region so it merges cleanly with #505.Test plan
make build-docsexits 0 —astro checkclean, starlight-links-validator clean, 21 pages builtmake verifypasses (run by the pre-commit hook on this commit's tree)dist/index.html(splash homepage) anddist/404.htmldeployment,durability): content → CloudCta → PageFeedback → edit link → prev/nextgetting-started): content → PageFeedback → edit link → prev/next.sl-markdown-content, not inside it, so markdown prose styles don't leak into itdocs_feedbackappears once in the built HTML[data-state="voted"]show/hide rules present in the built CSS bundlemarkdownlint-cli2 CHANGELOG.mdreports 0 issuesRelated Issues
None