feat: forward known utm params from homepage to get-started CTA links

[claude]

Requested by Elliot Hesp · Slack thread

Summary

Before: a visitor arrives at docs.page/?utm_source=twitter&utm_campaign=launch. The page view is captured with those params, but the two "Get started" buttons render as bare /get-started links. When the visitor clicks, /get-started sees no utm params on its own request URL, so homepage:cta_click lands with no attribution — the campaign gets credit for the visit but not for the click.

After: the same visit renders both buttons as /get-started?utm_source=twitter&utm_campaign=launch, so the click event carries the same attribution as the page view and a flight's page-view → CTA-click funnel reconciles in PostHog.

Why: without it, paid and referral traffic cannot be attributed past the first hop, which makes the homepage CTA conversion rate unmeasurable per campaign.

How: app/src/lib/utm.ts gains utmQueryString(url), which reuses the existing utmProperties() helper so the five recognised param names stay a single source of truth, and re-encodes them via URLSearchParams (empty string when none are present). The homepage branch of getServerSideProps in app/src/pages/[[...path]].tsx computes it once and passes it as a utmQuery prop down to the hero and footer CTAs. Only the five known keys are forwarded — the inbound query string is never passed through wholesale, so no arbitrary param can be reflected into an on-page link, and the CTA href prefix stays a hardcoded relative path. /get-started itself is unchanged; it already reads utm params off its own request URL. No new dependencies, no client-side PostHog.

Scope

• app/ (hosted site, MCP, Ask AI)
• packages/cli/
• packages/mdx-bundler/
• docs/ (product documentation)
• Repo / CI / other

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / chore

Test plan

• bun run check passes locally (and biome ci .)
• bun test — 147 pass, 0 fail
• bunx tsc --noEmit -p app/tsconfig.json — clean
• cd app && bun run build — production build succeeds
• Updated docs/ (if user-facing) — n/a, internal analytics plumbing
• Verified on a docs.page URL or local preview (if rendering/routing changed) — pending Railway preview

New unit tests in app/src/lib/utm.test.ts cover no params, a subset, all five, unknown params dropped, and values needing encoding (the utm_campaign field has historically carried injection-probe strings, so the encoding case asserts the value cannot break out of the link).

Notes for reviewers

Prop drilling is two levels deep (Homepage → Hero / Footer); a context felt like more machinery than the one string warrants, but happy to change it.

Worth a check on the Railway preview with ?utm_source=x&utm_campaign=y appended, confirming both button hrefs carry the params and that a param that is not one of the five is dropped.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JdRBhYmUnmC9vbc7fcgXdC

---

Generated by Claude Code

[railway-app]

🚅 Deployed to the docs.page-pr-549 environment in docs.page

Service	Status	Web	Updated
docs.page	✅ Success (View Logs)	Web	Sep 8, 2026 at 8:42 am UTC

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}