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.

website/tools/search_gate.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
-"""The search gate: ten queries a visitor types, and the pages that answer them.
+"""The search gate: queries a visitor types, and the pages that answer them.
 
-Runs measure.mjs against a served build and counts a query as answered when
-one of its expected pages is in the first three results of the site's own
-search box.
+Runs measure.mjs against a served build, through the site's own search box,
+and checks each query's expected pages against the rank it must reach: the
+first result, or the first three.
 
     python website/tools/search_gate.py http://127.0.0.1:4321/retrobios/
 """
@@ -17,21 +17,24 @@ from pathlib import Path
 
 TOOLS = Path(__file__).resolve().parent
 
-# Query, then the pages that answer it (path prefixes under the site).
-QUERIES: dict[str, tuple[str, ...]] = {
-    "playstation bios": ("systems/sony/",),
-    # The file itself: its card on the system page, or a core that reads it.
-    "scph5501": ("systems/sony/", "emulators/beetle_psx/", "emulators/duckstation/",
-                 "emulators/duckstation-legacy/", "emulators/pcsx1/", "emulators/swanstation/",
-                 "emulators/ares/", "emulators/pcsx_rearmed/", "files/"),
-    "batocera folder": ("platforms/batocera/",),
-    "neogeo.zip": ("emulators/fbneo", "emulators/mame", "systems/snk/", "systems/arcade"),
-    "duckstation": ("emulators/duckstation/", "emulators/duckstation-legacy/"),
-    "steam deck": ("platforms/emudeck/", "platforms/retrodeck/", "which-pack/"),
-    "missing bios": ("wiki/troubleshooting/", "wiki/what-are-bios-files/", "wiki/faq/"),
-    "md5": ("wiki/verification-modes/",),
-    "retroarch system folder": ("platforms/retroarch/",),
-    "knulli": ("platforms/knulli/",),
+# Query: (pages that answer it, as path prefixes under the site, and the rank one
+# of them must reach). An emulator name must find the emulator itself first,
+# not its launcher or a frozen copy.
+QUERIES: dict[str, tuple[tuple[str, ...], int]] = {
+    "batocera folder": (("platforms/batocera/",), 1),
+    "missing bios": (("wiki/troubleshooting/", "wiki/what-are-bios-files/", "wiki/faq/"), 1),
+    "neogeo.zip": (("emulators/fbneo", "emulators/mame", "systems/snk/", "systems/arcade"), 1),
+    "retroarch system folder": (("platforms/retroarch/",), 1),
+    "installer": (("wiki/installer/", "wiki/first-install/"), 1),
+    # The file's card on its system page, where it is downloaded.
+    "scph5501": (("systems/sony/",), 3),
+    "md5": (("wiki/verification-modes/",), 1),
+    "where do bios files go": (("which-pack/", "wiki/first-install/"), 1),
+    "dolphin": (("emulators/dolphin/",), 1),
+    "duckstation": (("emulators/duckstation/",), 1),
+    "playstation bios": (("systems/sony/",), 3),
+    "steam deck": (("platforms/emudeck/", "platforms/retrodeck/", "which-pack/"), 1),
+    "knulli": (("platforms/knulli/",), 1),
 }
 
 
@@ -48,12 +51,14 @@ def main() -> int:
         if "query" not in result:
             print(f"first search: {result['first_search_kb']} KB in {result['first_search_requests']} requests")
             continue
-        top = [entry.split(" | ")[1][len(root):] for entry in result["top"][:3]]
-        hit = any(page.startswith(QUERIES[result["query"]]) for page in top)
+        pages, rank = QUERIES[result["query"]]
+        top = [entry.split(" | ") for entry in result["top"][:3]]
+        hit = any(href[len(root):].startswith(pages) for _title, href in top[:rank])
         answered += hit
-        print(f"{'ok  ' if hit else 'MISS'} {result['query']!r}: {', '.join(top)}")
-    print(f"{answered}/{len(QUERIES)} queries answered in the top 3")
-    return 0 if answered >= 9 else 1
+        titles = "; ".join(title for title, _href in top)
+        print(f"{'ok  ' if hit else 'MISS'} {result['query']!r} (top {rank}): {titles}")
+    print(f"{answered}/{len(QUERIES)} queries answered")
+    return 0 if answered == len(QUERIES) else 1
 
 
 if __name__ == "__main__":

website/tools/search_scores.mjs

@@ -6,18 +6,18 @@ const [base, query, ranking] = process.argv.slice(2);
 const browser = await chromium.launch({ executablePath: '/usr/bin/google-chrome' });
 const page = await browser.newPage();
 await page.goto(base, { waitUntil: 'networkidle' });
-const rows = await page.evaluate(async ({ root, query, ranking }) => {
+const rows = await page.evaluate(async ({ root, query, ranking, top }) => {
 	const pagefind = await import(`${root}pagefind/pagefind.js`);
 	if (ranking) await pagefind.options({ ranking: JSON.parse(ranking) });
 	const search = await pagefind.search(query);
-	const top = search.results.slice(0, 8);
-	const data = await Promise.all(top.map((result) => result.data()));
-	return top.map((result, index) => ({
+	const shown = search.results.slice(0, top);
+	const data = await Promise.all(shown.map((result) => result.data()));
+	return shown.map((result, index) => ({
 		score: result.score.toFixed(3),
 		url: data[index].url,
 		words: data[index].word_count,
 		hits: result.words.length,
 	}));
-}, { root: base, query, ranking });
+}, { root: base, query, ranking, top: Number(process.env.TOP || 8) });
 for (const row of rows) console.log(row.score, row.words, row.hits, row.url);
 await browser.close();