2 Commits

Include renames

Author	SHA1	Message	Date
Pamela Chia	770f1c2b06	fix(aeo): remove ua-based markdown serving (#47770) ... ## Summary The `ChatGPT-User` live-fetch agent's user-facing reader hard-fails (`(400) OK`) on pages we serve it as markdown via user-agent matching, which made supabase.com blog and product pages unreadable in that assistant. I root-caused this with a controlled fetch diagnostic cross-checked against our request logs: the failing fetches never reach our origin (the failure is cached on their side), pages served as plain HTML read fine everywhere we tested, and the same failure reproduces on other major sites that serve UA-matched markdown, so the reader bug is upstream. This PR removes user-agent-based markdown serving entirely rather than special-casing one agent: UA sniffing is a guess about contractless clients whose fetchers change without notice, and this incident showed the failure mode is silent (we keep serving 200s while the user-facing agent breaks). Markdown remains available on every explicit signal — `Accept: text/markdown` q-value negotiation, explicit `.md` URLs, and llms.txt — which is the same contract-driven model the Claude fetcher already uses successfully (it sends `Accept: text/markdown, text/html, */*` and keeps receiving markdown after this change). ## Changes - Remove the `LLM_USER_AGENT` regex and the `userAgent` parameter from `negotiateMarkdown` in `packages/common/markdown-negotiation.ts`; decisions now depend only on `Accept`, the `.md` suffix, and the markdown-variant manifest - Update both consuming middlewares (`apps/www`, `apps/docs`) to the new signature; no behavior change for Accept-negotiated or `.md` requests - Add the missing `Vary: Accept` header to docs guides-md 200 responses (the www `api-v2/md` route already declares it) - Fix a pre-existing www bug surfaced in review: explicit changelog `.md` URLs rewrote to a doubled `.md.md` path (404) under a markdown-preferring `Accept`, and 406'd on a non-matching `Accept`. The www middleware now strips the `.md` suffix before slug lookup and passes `isMarkdownSuffix` into `negotiateMarkdown`, folding the separate `MD_PAGES` `.md` block into the single negotiation path (same shape as the docs middleware) - Rework tests: UA-independence suites replace the per-agent rewrite tests; a probe Accept header now 406s regardless of user agent (previously agent UAs were exempt); new changelog `.md` negotiation coverage ## Testing Tested locally: - [x] www middleware suite 36/36, docs middleware suite 17/17 - [x] typecheck green for common, www, docs Verified on the Vercel previews (www + docs) with curl: - [x] `ChatGPT-User` and `Claude-User` UA GETs on blog/pricing/guide pages return `text/html` with a default Accept - [x] Claude's real Accept (`text/markdown, text/html, */*`) still returns `text/markdown`; `Accept: text/markdown` and `.md` URLs return `text/markdown`; probe Accept returns 406 - [x] `/changelog/<slug>.md` with `Accept: text/markdown` returns the entry markdown as a direct 200 (production today detours through a 308 to the bare URL); changelog index `.md` and bare-entry Accept negotiation also verified - [x] docs guides markdown 200s carry `Vary: Accept` The intermediate commit (ChatGPT-User-only exclusion) was already verified on the preview: `ChatGPT-User` got HTML while `Accept`/`.md`/other-UA markdown was unaffected. Expected effects post-merge: UA-driven markdown volume in the request logs (~92% of md traffic) collapses to the Accept + `.md` baseline; named-agent page requests return to prerendered/static serving, reversing the extra Vercel function invocations the UA rewrite introduced; user-facing readability in the affected assistant recovers within ~24h as its fetch cache revalidates. The md-share dashboard gets a dated annotation; the ratio is not comparable across this change. ## Linear - fixes GROWTH-973 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Markdown and HTML routing now depends on the request’s `Accept` header and `.md` links, making content negotiation more predictable. * Requests that don’t accept available content now consistently return `406 Not Acceptable`, even for bot-like user agents. * Guide markdown responses now include an `Accept`-based cache variation header to improve correct caching behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-10 13:50:34 +08:00
Pamela Chia	cd52669f1f	fix(docs): negotiate /guides/* markdown via shared helper (#45432) ... ## Summary This brings docs `/guides/*` to full content negotiation for AI agents (GROWTH-811): RFC 9110 q-value parsing instead of a `.includes('text/markdown')` substring match, a 406 when the client rejects every type the route can produce, and markdown rewrites for known LLM user agents. I implemented it by extracting the negotiation into a shared `common/markdown-negotiation` module consumed by both `apps/docs/middleware.ts` and `apps/www/middleware.ts`, rather than duplicating the helpers into docs and keeping them in sync by hand with www (#45394). Single source of truth, no re-sync burden. www is refactored onto the shared helper with no behavior change. ## Changes ### docs `/guides/*` content negotiation (GROWTH-811) - Replace the `.includes('text/markdown')` substring match with RFC 9110 q-value parsing. - Return 406 (`Cache-Control: no-store`, `Vary: Accept`) when Accept excludes every type the route serves. Bypassed for LLM user agents, the `.md` suffix, and clients sending no Accept. - Rewrite to `/api/guides-md/<slug>` for LLM user agents (Claude-User, Claude-Web, ChatGPT-User, PerplexityBot) regardless of Accept. - Preserve the existing `.md` suffix routing and the entire `/reference/*` block. ### Shared negotiation helper - New `packages/common/markdown-negotiation.ts`: `negotiateMarkdown(signals, route)` returns `'markdown' | 'not-acceptable' | 'pass'`. Internalizes q-value parsing, the LLM user-agent match, the UA-length cap, and the markdown-vs-html preference. - `apps/www/middleware.ts`: refactored to consume the shared helper; its duplicated copy of the negotiation helpers (added in #45394) is removed. `.md` early-return, changelog routing, and first-referrer cookie stamping are unchanged (no behavior change, covered by its existing tests). ### Tests - New `apps/docs/middleware.test.ts`: q-value priority, the 406 path, `.md` suffix, LLM UA override, browser default Accept, training-crawler and substring-embed exclusion, and the `/reference/*` exemption. - New `packages/common/markdown-negotiation.test.ts`: the same decision matrix at the unit level (q-values, 406, LLM UAs, `.md`, `*/*`, training crawlers, OWS, out-of-range q). ## Testing (Vercel preview) After Vercel posts a preview URL, save it once then run the probe set. ```bash echo 'PREVIEW_HOST' > /tmp/growth-811-host.txt HOST=$(cat /tmp/growth-811-host.txt) # 1) Browser-style Accept -> HTML 200 curl -sI -A "Mozilla/5.0" \ -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8' \ "https://$HOST/docs/guides/auth" # 2) Accept: text/markdown -> markdown 200 curl -sI -H 'Accept: text/markdown' "https://$HOST/docs/guides/auth" # 3) text/html;q=1.0, text/markdown;q=0.5 -> HTML 200 curl -sI -H 'Accept: text/html;q=1.0, text/markdown;q=0.5' "https://$HOST/docs/guides/auth" # 4) unsupported Accept -> 406 + Cache-Control: no-store + Vary: Accept curl -sI -H 'Accept: application/x-content-negotiation-probe' "https://$HOST/docs/guides/auth" # 5) User-Agent: Claude-User/1.0 (any Accept) -> markdown 200 curl -sI -A 'Claude-User/1.0' "https://$HOST/docs/guides/auth" ``` ### After merge Run [acceptmarkdown.com/readiness-check](https://acceptmarkdown.com/readiness-check) against `https://supabase.com/docs/guides/auth`: expect 100/100. ## Linear - fixes GROWTH-811	2026-06-09 17:49:35 +08:00