Convert the documentation site from Docusaurus to Starlight

.github/workflows/main.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20.5.1
+          node-version: 22
 
       - name: Install dependencies
         run: npm install
@@ -25,7 +25,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: build
-          path: build
+          path: dist
           retention-days: 1
 
   deploy:
@@ -38,15 +38,15 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: build
-          path: build
+          path: dist
 
       - name: Rsync Deployer
         uses: imajeetyadav/rsync-deployer@1.0.0
         with:
           HOST: ${{ secrets.SERVER_IP }}
           USERNAME: ${{ secrets.SSH_USER }}
           KEY: ${{ secrets.SSH_PRIVATE_KEY }}
-          SOURCE_PATH: "./build/"
+          SOURCE_PATH: "./dist/"
           TARGET_PATH: "~/roqua_docs/html/"
           PORT: 22
           RSYNC_PARAMETERS: ""

.gitignore

@@ -1,15 +1,15 @@
 # Dependencies
 /node_modules
 
-# Production
-/build
+# Build output
+/dist
 
-# Generated files
-.docusaurus
-.cache-loader
+# Generated types
+.astro/
 
 # Misc
 .DS_Store
+.env
 .env.local
 .env.development.local
 .env.test.local

README.md

@@ -1,41 +1,64 @@
-# Website
+# RoQua Documentation
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+The site published at [docs.roqua.net](https://docs.roqua.net), built with
+[Starlight](https://starlight.astro.build/) on [Astro](https://astro.build/).
 
-### Installation
+## Development
 
 ```
-$ yarn
+npm install
+npm start          # dev server on http://localhost:3030
+npm run build      # static site into dist/
+npm run preview    # serve the built site
+npm run typecheck  # astro check
 ```
 
-### Local Development
+Pushing to `master` builds the site and rsyncs `dist/` to the web server; see
+`.github/workflows/main.yml`.
 
-```
-$ yarn start
-```
+## Where content lives
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+All pages are one Astro content collection under `src/content/docs/`:
 
-### Build
+| Path                        | URLs               | Notes                                     |
+| --------------------------- | ------------------ | ----------------------------------------- |
+| `docs/`                     | `/docs/**`         | User manual (Dutch)                       |
+| `technical/`                | `/technical/**`    | Integration-partner docs (English)        |
+| `en/`                       | `/en/**`           | English translations                      |
+| `index.mdx`, `status.md`    | `/`, `/status/`    | Homepage and server status                |
 
-```
-$ yarn build
+Dutch is the root locale, so Dutch pages sit at the top level and their English
+counterparts mirror the same path under `en/`. A page with no translation falls back
+to the Dutch file, so `/en/technical/…` works without duplicating those files.
+
+Files use the `.mdx` extension throughout, because pages mix Markdown with the
+components in `src/components/`. Those must be imported per file — there is no global
+component scope:
+
+```mdx
+import Screenshot from "@components/Screenshot.astro";
+
+<Screenshot src="/screenshots/overzicht.png" />
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+Available components: `Icon`, `Screenshot`, `ScreenshotRow` and `Snapshot` (renders an
+API example as HTTP/cURL/PowerShell tabs from a fixture in `src/data/snapshots/`).
 
-### Deployment
+Images referenced by URL live in `public/` (`/screenshots/**`, `/icons/**`, `/img/**`,
+`/files/**`). Images placed next to a page and linked relatively are optimised by Astro.
 
-Using SSH:
+## Sidebar
 
-```
-$ USE_SSH=true yarn deploy
-```
+Top-level sections and their translated labels are set in `astro.config.mjs`; the pages
+inside them are discovered automatically. Ordering comes from `sidebar.order` in each
+page's frontmatter (lower first, unset sorts last alphabetically). A directory's
+position is the lowest `order` of the pages it contains.
 
-Not using SSH:
+Group labels are taken from the title of the directory's `index.mdx`, via
+`src/starlightRouteData.ts` — so a new subdirectory only needs an index page to get a
+readable label.
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
+## Release notes
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+`changelog/` holds release notes pushed here by other repositories' CI. They are not
+currently published as part of the site.

astro.config.mjs

@@ -0,0 +1,66 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+
+export default defineConfig({
+  site: "https://docs.roqua.net",
+
+  // The manual root used to be /docs/index/, an artifact of the `01-index.md`
+  // numeric prefix. It was the navbar's "User Manual" target, so keep it working.
+  redirects: {
+    "/docs/index": "/docs/",
+    "/en/docs/index": "/en/docs/",
+  },
+
+  integrations: [
+    starlight({
+      title: {
+        nl: "RoQua Documentatie",
+        en: "RoQua Documentation",
+      },
+      logo: {
+        src: "./src/assets/roqua-q.png",
+        alt: "RoQua Logo",
+      },
+      favicon: "/img/favicon.ico",
+
+      defaultLocale: "root",
+      locales: {
+        root: { label: "Nederlands", lang: "nl" },
+        en: { label: "English", lang: "en" },
+      },
+
+      editLink: {
+        baseUrl: "https://github.com/roqua/documentation/edit/master/",
+      },
+
+      customCss: ["./src/styles/custom.css"],
+
+      // Recovers the Docusaurus category labels for autogenerated groups.
+      routeMiddleware: "./src/starlightRouteData.ts",
+
+      sidebar: [
+        {
+          label: "Gebruikershandleiding",
+          translations: { en: "User Manual" },
+          items: [{ autogenerate: { directory: "docs", collapsed: true } }],
+        },
+        {
+          label: "Technische handleiding",
+          translations: { en: "Technical documentation" },
+          items: [{ autogenerate: { directory: "technical", collapsed: true } }],
+        },
+        { slug: "status" },
+      ],
+    }),
+  ],
+
+  vite: {
+    resolve: {
+      alias: {
+        "@components": new URL("./src/components", import.meta.url).pathname,
+        "@snapshots": new URL("./src/data/snapshots", import.meta.url).pathname,
+      },
+    },
+  },
+});