[bpamiri]

Summary

Moves the five static sites (web/sites/{landing,blog,guides,api,packages}) from Astro 6 to Astro 7.3.5, and the two Starlight sites (guides, api) to Starlight 0.42.5. The lockfile is regenerated, so dependencies resolve fresh within their ranges.

Changes

• web/sites/*/package.json: astro → ^7.3.5. guides and api: @astrojs/starlight → ^0.42.5, and add @astrojs/markdown-remark@^7.3.1. Astro 7 no longer installs it by default (Sätteri is the default Markdown processor), but these two sites use markdown.remarkPlugins / rehypePlugins, and Starlight 0.42 lists it as a peer.
• web/packages/ui/package.json: astro peer range ^5.0.0 → ^7.0.0.
• Root web/package.json pnpm.overrides:
  • removed astro: ^6.3.1, which pinned every site to Astro 6;
  • esbuild ^0.27.3 → ^0.28.1;
  • fast-uri ^3.1.2 → ^3.1.8;
  • yaml and fast-xml-builder unchanged.
• web/pnpm-lock.yaml: regenerated from scratch.

No source or config code had to change for Astro 7 / Starlight 0.42. The Head/Header overrides, sidebars, the llms endpoints and the content collections build as they are.

Supersedes the manifest-only alignment in #4360: once both merge, these specifiers win.

Rendering changes in Astro 7, and how they're handled

• Whitespace (fixed): Astro 7 changed the compressHTML default from true to 'jsx', which drops the space between text and an element on the next line. The packages site rendered "Install withwheels packages add(in Wheels 4.2…" and "alias of it;add". All five sites now set compressHTML: true, Astro 6's HTML-aware compression. With it, the visible text of landing and packages is identical to the Astro 6 build. Blog, guides and api differ only by extra whitespace between table cells and select options, which doesn't change how they look.
• Typographic quotes (accepted): Astro 6 applied smartypants to .md pages but not .mdx, so the api site and the .md guides already used curly quotes while the .mdx guides used straight ones. Astro 7 applies it to .mdx too, so prose quotes are now consistent site-wide. Code is unaffected: no <pre> or <code> element in the guides has a curly quote, and the api's code text is unchanged from Astro 6.
• Starlight 0.42: the "On this page" column sits about 8px differently, and the mobile menu button has a "Menu" label.
• Visual baselines: guides.png and api.png were refreshed for the quotes and the TOC shift. Nothing else changed: the packages and landing baselines match again once compressHTML is restored.

Verification (develop + this branch)

• pnpm install --frozen-lockfile passes.
• pnpm build: all five sites, with the same page counts as on Astro 6:

site	pages
landing	1
blog	357
packages	8
guides	852
api	3136

• node scripts/check-llms.mjs: passes for guides and api (current version v4-1-0). Its fixture tests are 7/7.
• Crawl (every sitemap and RSS URL, and every internal link, resolved against dist/): identical to the Astro 6 build:
  • blog sitemap 357/357, RSS 205/205;
  • packages sitemap 8/8;
  • internal links unchanged. The old /blog/<slug> links are handled by the redirects in fix(web): return a real 404 for unknown paths on wheels.dev, blog and packages #4358.
• Resolved: astro 7.3.5, @astrojs/starlight 0.42.5, esbuild 0.28.2, fast-uri 3.1.8.

Visual baselines may change with Astro 7's rendering. I'll check the visual-regression diffs and refresh only what changed.

🤖 Generated with Claude Code

[bpamiri]

rev1-r3 review @ 0a67705: approve in substance. Per orch1, the final comes on the post-develop-merge head after #4360 lands.

• The Head override still matches Starlight's. Starlight 0.42.5 ships its Head at dist/components/Head.astro, and it's still exactly const { head } = Astro.locals.starlightRoute; followed by {head.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}. That's what the override renders before <FontPreload />. The version comment is bumped to 0.42.5, so it's re-synced correctly.
• The other UI overrides (Header, Footer, SocialIcons) import nothing from @astrojs/starlight, so the package's move to dist/ can't break their imports. Your five builds with unchanged page counts, plus check-llms on guides and API, are the evidence that they still render inside 0.42's layout.
• Dependencies.
  • The astro override is removed, the sites move to ^7.3.5, and the UI peer to ^7.0.0.
  • @astrojs/markdown-remark ^7.3.1 is added to guides and API, which use remark/rehype plugins.
  • The esbuild and fast-uri overrides are bumped.
  • The regenerated lockfile resolves astro@7.3.5 and starlight@0.42.5, with no astro@6 left anywhere.
• Ordering. This undoes build(web): make the astro specifiers match the Astro 6 the sites build with #4360's ^6.3.1 manifests, by design. Once build(web): make the astro specifiers match the Astro 6 the sites build with #4360 merges, this branch needs a develop merge: the five site package.jsons and the UI peer will conflict, and should resolve to this PR's values, with the lockfile regenerated. I'll re-check that the merged head's manifests and lockfile agree (frozen install) and read its PR CI, including the builds, check-llms and visual regression. If the bot refreshes baselines, I'll check that delta is images only.

[bpamiri]

rev1-r3 @ 990ac25: merge verified; final held on Visual regression (one decision needed first)

• The merge is clean. Every web manifest, pnpm-lock.yaml and starlight/Head.astro are byte-identical to the approved 0a677051a, so the develop merge brought nothing else in.
• PR CI: 19 pass, 1 fail (Visual regression), 3 skipped. All five Deploy … builds pass, and check-llms passed on both docs builds ("current version v4-1-0").

I compared the visual-regression-diffs artifact with the baselines. guides, api, packages-index and packages-wheels-sentry differ; landing and blog don't. Two separate changes cause it:

1. Typography (guides and api, prose from Markdown). Straight quotes and apostrophes now render as curly ones: You'll → You’ll, "Where we left off" → “Where we left off”. That's Markdown "smartypants" now applying to Starlight's content under Astro 7 / @astrojs/markdown-remark 7. Code blocks are unaffected, and the .md twins and llms-*.txt come from source, so they're unchanged too.
2. Layout (Starlight 0.42). The right-hand "On this page" column moved about 8 px left, and the content column is correspondingly narrower. The packages pages differ only in a small region around the inline wheels packages add code in the intro.

None of it is a break. But (1) is a site-wide content-appearance change, so it should be decided rather than just baselined. Curly quotes are the typographic norm, but site search (Pagefind) indexes the rendered text, so a search typed with a straight apostrophe (don't) may not match don’t in the pages. If you'd rather keep today's rendering, set markdown: { smartypants: false } in the guides and API configs. If you're happy with curly quotes, refresh the four baselines.

Either way, send me the head after the refresh (plus the human empty commit, so CI runs). I'll confirm the refresh commit touches only those four PNGs and give the final.

[bpamiri]

rev1-r3 re-review @ 5fc85110c62a: content APPROVE; final once a human commit re-runs CI on this head

The delta since 990ac259c:

• d4b459a58 adds compressHTML: true (with a comment explaining Astro 7's 'jsx' default) to exactly the five astro.config.mjs files. Nothing else changed.
• 5fc85110c (github-actions bot) touches only web/tests/visual-baselines/guides.png. The other baselines were evidently unchanged after compressHTML.

Code samples keep straight quotes. I fetched four built pages from this branch's guides preview (ab1f9316.wheels-guides.pages.dev, the d4b459a58 deploy) and counted quote characters inside <code> versus prose:

page	in code: curly / straight	curly in prose
v4-1-0 basics/routing	0 / 103	25
v4-1-0 basics/controllers-and-actions	0 / 116	48
v4-2-0 basics/controllers-and-actions	0 / 126	52

So smart quotes apply only to prose. Code blocks and inline code are untouched, which matches the decision to keep smartypants on for consistency with the existing .md pages.

5fc85110c is a bot push, so it has no checks. Please add the empty human commit; I'll give the final on that head's PR CI (all five deploys, check-llms, and Visual regression green).

[bpamiri]

rev1-r3 review @ b4c8950: APPROVE (final)

The content was approved earlier on this head. For a web PR the gate is PR CI, and it is now 21 pass / 0 fail / 0 pending, with 2 skipping. The one earlier red check, the infra adobe2023 + sqlite job (an HTTP 500 from the CF engine before any test ran), passed on its re-run: run 37360030159, attempt 2, success.

Ready to merge.