Convert the documentation site from Docusaurus to Starlight

[marten]

Replaces Docusaurus 3.9 with Astro 7 + Starlight 0.41. One third-party Starlight plugin: starlight-links-validator, which fails the build when an internal link points at a page or anchor that doesn't exist.

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.

With the blog and changelog gone, their RSS/Atom feeds are gone too — decided, not an oversight.

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/.
• Indented code blocks → fenced. MDX silently dropped support for indentation-based code blocks, so ~30 of them (HL7 messages, API endpoint lines, SSO URLs) rendered as body text — the HL7 ~ repetition separators even turned into strikethrough. All fenced now.
• The two custom heading anchors ({#show}, {#index}) are gone in favour of autogenerated slugs; {#id} is not valid MDX and nothing links to them.

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.

Decided: the manual and the technical docs stay as two groups in one global sidebar. starlight-sidebar-topics could restore Docusaurus's separate per-section sidebars, but one sidebar is clean and easy.

The two English sidebar labels that read Dutch ("Beheermodule", "Overig") are fixed: the group labels come from index pages, and those two had no English translation. They do now.

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, image optimisation, and build-time link validation.

On link validation: the old site had 27 broken content links that Docusaurus only warned about. All are fixed on this branch — old rom_manual//developer/ URL structures remapped to the pages' current homes, renamed export pages relinked, stale anchors corrected. starlight-links-validator now fails the build if one regresses. (It also flagged that empty-bodied index pages are invisible to it, so the docs/epd/ and technical/rest_api/ landing pages got the one-line intros they should have had anyway.)

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.

---

One note outside the conversion's scope: the English translations of the manual pages edited on this branch (en/docs/index.mdx, en/docs/features/index.mdx, en/docs/epd/overview/index.mdx, en/docs/epd/measure/measurements/index.mdx) still carry the earlier text. They have translations, so they don't fall back — routine content work for whenever the English manual gets attention.

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	Aug 14, 2026 10:25am