Convert the documentation site from Docusaurus to Starlight

[marten]

Replaces Docusaurus 3.9 with Astro 7 + Starlight 0.41. No third-party Starlight plugins.

Builds 157 pages, npm run typecheck (astro check) reports 0 errors.

URL parity

I captured every URL the Docusaurus build produced before starting and diffed the Starlight output against it. The only differences are intentional:

Change	Why
/docs/index/ → /docs/	The old path was an artifact of the 01-index.md numeric prefix. It was the navbar's "User Manual" target, so a redirect keeps it working.
/markdown-page/ removed	Unused Docusaurus template leftover.
/changelog/** removed	Not published any more, as agreed. The markdown stays in changelog/, so the CI that pushes release notes there keeps working.
/blog/** removed	Blog dropped; its content is being folded into the manual.

Everything else — all of /docs/**, /technical/**, /status/, and the /en/** mirror — resolves at exactly the same URL as before.

How the content moved

docs/, technical/ and i18n/en/ collapse into one content collection under src/content/docs/, tracked as renames so history follows. Mechanical conversions:

• Numeric path prefixes stripped (Docusaurus stripped them from URLs, Starlight does not).
• # Heading hoisted into title: frontmatter, which Starlight renders as the H1. Where a file had both, the old frontmatter title became sidebar.label.
• :::info → :::note. Starlight has no info variant and renders unknown ones as an unstyled div, with no build warning.
• HTML comments → {/* */}. Docusaurus stripped them before MDX parsing; Astro does not.
• require() snapshot fixtures → ESM imports, now in src/data/snapshots/.

Every page is .mdx, because Docusaurus already parsed all .md as MDX. Plain .md would silently change how the JSX and {…} in these files parse.

Sidebar

Labels and ordering match the old site exactly. Ordering is encoded in sidebar.order: Starlight gives a directory the lowest order of its children, so the old NN- prefixes translate faithfully. Group labels come from each directory's index-page title via src/starlightRouteData.ts, which keeps Docusaurus's behaviour — a new subdirectory only needs an index page to get a readable label, no config edit.

Components

Icon, Screenshot, ScreenshotRow and Snapshot are now Astro components. The hand-rolled tab widget is gone in favour of Starlight's <Tabs>, which is keyboard-accessible and syncs, so choosing cURL once applies to every request on the page.

There is no global component scope in MDX, so pages import what they use. This is documented in the README.

Gained

Pagefind search (the old site had none), a sitemap, and image optimisation.

Deployment

master is self-hosted: the GitHub Actions workflow now uploads and rsyncs dist/ instead of build/.

Preview branches build on Vercel, whose project settings still had Docusaurus's build as the Output Directory, so previews failed even though the build succeeded. vercel.json now sets outputDirectory to dist and the framework preset to astro, overriding the dashboard so the setting is versioned with the code. It also sets trailingSlash: true to match Astro's directory output and the internal links Starlight generates.

Known gaps

• No RSS/Atom feeds. Docusaurus published /blog/rss.xml and changelog feeds; nothing regenerates them. Roughly 15 lines with @astrojs/rss if anyone subscribed.
• Two English sidebar labels read Dutch — "Beheermodule" and "Overig". Docusaurus translated sidebar labels separately from page content; Starlight takes them from the page, and those two index pages have no English translation. Translating them fixes it.
• 27 pre-existing broken content links are unchanged. Verified against Docusaurus's own warning log that this branch introduces none, and fixed 3 that would otherwise have regressed on trailing-slash resolution. Many of the 27 have an obvious intended target and are worth a follow-up.
• English pages lag on the pages edited in the second commit — en/docs/index.mdx, en/docs/features/index.mdx, en/docs/epd/overview/index.mdx and en/docs/epd/measure/measurements/index.mdx still hold the pre-edit text. They have translations, so they do not fall back.
• Two unreferenced heading anchors (#show, #index) became autogenerated slugs; {#id} is not valid MDX.

Not done, worth deciding

starlight-sidebar-topics would restore the separate per-section sidebars — the manual and the technical docs are currently two groups in one sidebar rather than independent ones.

https://claude.ai/code/session_018s8Dyz49WwNfkVF5zpT6ko

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview, Comment	Jul 25, 2026 6:05pm