feat: build the site with Astro Starlight

generate_site.py writes the Starlight project in website/ and nothing
else: mkdocs.yml, the MkDocs hooks, theme overrides and stylesheet go,
and the wiki is written in Starlight's syntax. Both workflows set up
Node with the official actions/setup-node pinned by commit, run npm ci
from the committed lockfile, build with the strict link validator and
check the result with validate_site.py.

The search weighs a page by what it answers: Start here pages first,
a system page's cards and file names before a guide citing them, deep
guides, launchers, aliases and frozen copies after. Status badges,
hash blocks and the export change lists leave the index. The ranking
sits at the centre of a range where the 13 queries of search_gate.py
all answer, in the search box itself.

839 pages, every URL and 45,611 ids match the MkDocs build. The tests
read the Starlight content and syntax.

.github/workflows/deploy-site.yml

@@ -29,7 +29,6 @@ on:
       - "scripts/largefiles.py"
       - "scripts/launchers.py"
       - "scripts/manifestselect.py"
-      - "scripts/mkdocs_hooks.py"
       - "scripts/nativemode.py"
       - "scripts/packextras.py"
       - "scripts/packpaths.py"
@@ -69,7 +68,9 @@ on:
       - "database.json"
       - "release.json"
       - "derivable.json"
-      - "mkdocs.yml"
+      # The Starlight project: config, components, styles, lockfile. Its
+      # generated folders are gitignored and never trigger anything.
+      - "website/**"
       - ".github/workflows/deploy-site.yml"
   workflow_dispatch:
 
@@ -95,11 +96,18 @@ jobs:
         with:
           python-version: "3.12"
 
-      # mkdocs-material >= 9.7.5 caps mkdocs < 2, and the upper bound keeps a major
-      # theme release from changing the site without a deliberate bump here.
-      # mkdocs is pinned below 2 on its own too: MkDocs 2 drops plugins, and the
-      # theme, in maintenance mode since 9.7.0, will not follow it.
-      - run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0" "mkdocs>=1.6,<2" "mkdocs-material>=9.7.5,<10" "pymdown-extensions>=10.14"
+      - run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0"
+
+      # Node builds the site only: the scripts stay Python. The engine and
+      # its plugins are pinned exactly in website/package.json and resolved
+      # from the committed lockfile.
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - run: npm ci --prefix website
 
       - name: Validate data contracts
         run: python scripts/validate_schemas.py
@@ -122,8 +130,9 @@ jobs:
         run: |
           python scripts/generate_site.py
           python scripts/generate_readme.py --db database.json --platforms-dir platforms
-          mkdocs build --strict
-          python scripts/validate_site.py
+          # starlight-links-validator fails the build on a dead link or anchor.
+          npm run build --prefix website
+          python scripts/validate_site.py --site-dir website/dist
 
       # write_if_changed() compares content with its timestamp line stripped,
       # so a run that only moves the clock leaves the file untouched and this
@@ -137,7 +146,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
         with:
-          path: site/
+          path: website/dist/
 
   deploy:
     needs: build

.github/workflows/validate.yml

@@ -29,7 +29,7 @@ on:
       - "database.json"
       - "release.json"
       - "derivable.json"
-      - "mkdocs.yml"
+      - "website/**"
   # Spelled out twice because the workflow parser reads no YAML anchor. A test
   # holds the two lists equal.
   push:
@@ -53,7 +53,7 @@ on:
       - "database.json"
       - "release.json"
       - "derivable.json"
-      - "mkdocs.yml"
+      - "website/**"
 
 permissions:
   contents: read
@@ -213,10 +213,18 @@ jobs:
         run: python3.9 -m pip install pyyaml "jsonschema[format-nongpl]==4.25.1"
 
       # markdown: the site validation test renders a wiki line to prove the
-      # heading guard's premise, and skipped on every run without it. The docs
-      # group builds the site as deploy-site.yml does, with the same bounds.
+      # heading guard's premise, and skipped on every run without it.
       - name: Install dependencies
-        run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0" "markdown==3.10.2" "mkdocs>=1.6,<2" "mkdocs-material>=9.7.5,<10" "pymdown-extensions>=10.14"
+        run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0" "markdown==3.10.2"
+
+      # The site is built as deploy-site.yml builds it, from the lockfile.
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - run: npm ci --prefix website
 
       # The exporter fidelity cases compare what we hand back against the
       # file each platform publishes, so they need those files. They skip
@@ -234,7 +242,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # docs/ is gitignored, and the tests that read the rendered pages fail
+      # The pages are gitignored, and the tests that read them fail
       # in CI without it. The suite runs whatever this step returned, so a
       # generator that stops still leaves every other test reporting.
       - name: Generate the site
@@ -256,8 +264,8 @@ jobs:
       - name: Build the site
         if: ${{ !cancelled() }}
         run: |
-          mkdocs build --strict
-          python scripts/validate_site.py
+          npm run build --prefix website
+          python scripts/validate_site.py --site-dir website/dist
 
   label-pr:
     runs-on: ubuntu-latest