fix: resolve /404 route collision and prerender header warnings#313
Conversation
Replace src/pages/404.astro (a second /404 route that collided with Starlight's built-in one, which Astro warns will become a hard error) with src/content/docs/404.mdx, Starlight's supported content-collection 404 override. The docs_404 Rudderstack tracking consumed by the weekly-404-monitor moves into a small Docs404Tracking.astro component and is preserved unchanged (event name + broken_url). Local build passes; the /404 collision warning is gone and docs_404 is present in the built 404.html. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR removes the project-level src/pages/404.astro route that collides with Starlight's injected /404 route, replaces it with Starlight's supported src/content/docs/404.mdx content override, and preserves the existing docs_404 Rudderstack tracking payload in a dedicated Astro component.
Concerns
- No blocking correctness, security, or spec-alignment concerns found in the annotated diff.
spec_context.mdreports that no approved or repository spec context was found, so there was no spec contract to validate beyond the PR description and diff.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
The content-negotiation middleware read request.headers on every route, which warned 'Astro.request.headers not available on prerendered pages' ~692x during the static build. Guard with context.isPrerendered so headers are only read for on-demand (SSR) requests; runtime markdown negotiation is unchanged. Build warnings drop from 692 to 0. Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
changed the title
2 participants
Summary
Two build-health fixes for the docs site, both surfaced while investigating the token-usage guide PR (#269) Vercel preview:
/404route collision (which Astro warns will become a hard error in a future version).Astro.request.headers-on-prerendered-pages warning (~692 per build).Changes
1.
/404route collisionsrc/pages/404.astro— a second/404route that collided with Starlight's built-in one (@astrojs/starlight/routes/static/404.astro).src/content/docs/404.mdx— Starlight's supported content-collection 404 override (get404Route→getEntry('docs', '404')), so there is a single prerendered/404route.src/components/Docs404Tracking.astro— holds thedocs_404Rudderstack tracking script (kept in an.astrocomponent because MDX parses{/}as expressions).2.
Astro.request.headerswarningsrc/middleware.ts(content negotiation) calledshouldServeMarkdown(request), readingrequest.headerson every route. During the static prerender pass there is no real request, so Astro warned "Astro.request.headersis not available on prerendered pages" ~692 times per build. Guarded withcontext.isPrerenderedso the header read only runs for on-demand (SSR) requests. Runtime markdown content negotiation is unchanged.Preserves the 404 monitoring pipeline
The custom 404 fires a
docs_404Rudderstack event with the broken URL, consumed by theweekly-404-monitoragent (queriesdocs_404from BigQuery). This PR keeps that contract identical — samedocs_404event name andbroken_url/referrerproperties — so the monitor is unaffected. Verified the built404.htmlstill contains the tracking.Validation
npm run buildpasses (346 pages)./404route-collision warning: gone.Astro.request.headerswarnings: 692 → 0.docs_404present in bothdist/404.htmland.vercel/output/static/404.html.style_lint: 0 issues on the new page.Context
Follow-up from the token-usage guide PR (#269): its failing Vercel preview led to investigating these. That Vercel failure was transient and is now green; this PR proactively removes the latent collision and clears the header-warning noise.
Conversation: https://staging.warp.dev/conversation/a00f71f5-5c1a-450b-ada7-0d6180380fe3
Co-Authored-By: Oz oz-agent@warp.dev