Skip to content

chore(deps): upgrade astro 4 → 7 and Starlight 0.25 → 0.42 - #105

Open
HughParry wants to merge 3 commits into
mainfrom
chore/astro-7-migration
Open

HughParry wants to merge 3 commits into
mainfrom
chore/astro-7-migration

Conversation

@HughParry

Copy link
Copy Markdown

Replaces Dependabot #88. That PR only bumped astro, so npm ci failed: Starlight 0.25 only works with astro 4. This does the full upgrade. Stacked on #104; merge that first.

What changed

  • astro 4.16.13 → 7.3.5, Starlight 0.25.0 → 0.42.4, and matching bumps to @astrojs/check, sitemap, astro-og-canvas, typescript, @types/node and sass. @astrojs/markdown-remark is added.
  • Tailwind is removed rather than upgraded, because it wasn't doing anything. No stylesheet had @tailwind directives, the built CSS had no Tailwind output, and the font setting sat outside theme so it was never applied. The brand colours are plain CSS variables and are kept in src/styles/theme.css.
  • Also removed, all unused: astro-auto-import, vite-plugin-json5, vite-plugin-node-polyfills and the .jsonc loader.
  • The content collection moves to the new content layer (src/content.config.ts, docsLoader()), and entry.slug becomes entry.id.
  • Starlight component overrides go from 14 to 5. The deleted ones either matched the defaults now or never rendered (no page has a hero, tutorial or githubURL). The sidebar tweaks (sub-page highlight, "EN" marker on untranslated pages) move to src/routeData.ts.
  • TableOfContents now wraps Starlight's default. The old one bundled the whole Starlight package into a browser script, which throws "Failed to resolve module specifier fs" on every page of the live site and breaks the TOC scroll highlight. That error is gone.

Effect
The site should look the same. A few small visible changes come from Starlight itself: the mobile menu is now a popover, the system font stack is slightly different, and the twitter:title/twitter:description tags are gone (og: tags remain).

Testing

  • npm ci, npm run lint, npm run build and astro check all pass locally with no peer-dependency errors.
  • The build makes 417 pages, the same as main, with identical output paths.
  • Compared against main's build: sidebar, TOC, headings and anchors, prev/next links, redirects, OG tags and 404 match on English, German and fallback-language pages. Side-by-side screenshots looked the same.
  • Worth a look on the Netlify preview before merging.

Replaces Dependabot PR #88, which could not install because Starlight
0.25 only accepts astro 4.

- astro 4.16.13 -> 7.3.5, @astrojs/starlight 0.25.0 -> 0.42.4
- add @astrojs/markdown-remark 7.3.1: astro 7 renders Markdown with
  Satteri by default, and our remark/rehype plugins need the unified
  processor
- @astrojs/check 0.9.10, @astrojs/sitemap 3.7.4, astro-og-canvas 0.13.2,
  typescript 5.9.3, @types/node 24.19.0 and sass 1.105.0 (vite 8 peers)
- remove the Tailwind integration: no stylesheet contained @tailwind
  directives, so it emitted no CSS. The site colours live in plain
  --sl-color-* variables, now in src/styles/theme.css
- remove unused astro-auto-import, vite-plugin-json5,
  vite-plugin-node-polyfills and the .jsonc loader (no json5/jsonc
  files exist)
- config: social links as an array, drop removed experimental flags,
  rollupOptions -> rolldownOptions, disable Starlight's heading links
  since rehype-autolink already adds them, register a route middleware
  and trim the component override list
- src/content/config.ts -> src/content.config.ts with docsLoader()
- entry.slug -> entry.id everywhere; tutorial sorting uses filePath
- import z from astro/zod (zod 4) and use z.url()
- drop the hero facepile schema extension (no page uses a hero)
- astro-og-canvas 0.13: await OGImageRoute, key pages by entry id and
  pass routePattern when reading its static paths
- write the downloaded OG font as a Uint8Array for newer @types/node
Starlight 0.32 moved route data from Astro.props to
Astro.locals.starlightRoute and removed @astrojs/starlight/props.

- Head, SiteTitle, MarkdownContent: read from starlightRoute
- TableOfContents: wrap the default component and append the
  contribute links and feedback button, instead of importing
  Starlight internals and bundling the whole integration into a
  client script (which threw "Failed to resolve module specifier fs")
- Sidebar: replaced by src/routeData.ts route middleware that keeps
  the sub-page highlighting and the EN marker for untranslated pages
- delete overrides that now match the defaults or never render:
  EditLink and PageTitle (no page sets githubURL or type), Hero (no
  page has a hero), MobileTableOfContents and Pagination (tutorial-only
  branches, and there are no tutorial pages), PageSidebar (only added
  an empty banner container)
Base automatically changed from chore/dependabot-rollup-2026-09-29 to main October 1, 2026 15:34
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

No updates since 2026-10-01T15:34:09Z (over 7 days), so this PR has been converted to draft. That stops it holding CI runners.

Nothing is lost — gh pr ready 105, or the "Ready for review" button, picks it straight back up. Add the keep-ready label to exempt it permanently.

Converting to draft disables auto-merge, so PRs with auto-merge enabled are excluded from this entirely.

@github-actions

Copy link
Copy Markdown

No updates since 2026-10-09T07:10:36Z (over 7 days), so this PR has been converted to draft. That stops it holding CI runners.

Nothing is lost — gh pr ready 105, or the "Ready for review" button, picks it straight back up. Add the keep-ready label to exempt it permanently.

Converting to draft disables auto-merge, so PRs with auto-merge enabled are excluded from this entirely.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants