docs: sitemap.xml lists only the site root (option B)

Researched and confirmed: 68 of the site's 69 pages return a genuine
HTTP 404 status (GitHub Pages has no server-side rewrite, so
routerMode: 'history' relies on the 404.html fallback trick — correct
content, wrong status code). Google's own documentation confirms a
4xx status is a hard stop for indexing regardless of rendered content
(developers.google.com/search/docs/crawling-indexing/http-network-errors).
A sitemap listing all 69 would just be 68 confirmed-dead entries in
Search Console's coverage report.

generate_sitemap.py now emits a single <url> entry for the site root
only, which does return a real 200. Documented the reasoning in the
script's own docstring and in a new MAINTAINING_DOCS_SITE.md section,
including the path back (build-time pre-rendering to static files per
route) if this gets revisited later.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bjo12itgeoZW8rPFPXUZvz

Author: tedsluis

MAINTAINING_DOCS_SITE.md

@@ -55,6 +55,27 @@ and kept correct mechanically, not by hand:
 If you add a brand-new page, run `./scripts/ensure_footers.py` once (same as the sidebar-generation
 step above) rather than typing the footer by hand.
 
+## sitemap.xml lists the site root only, on purpose
+
+`scripts/generate_sitemap.py` (run automatically by
+`.github/workflows/update-sitemap.yml` on every push touching a `.md` file) generates
+`sitemap.xml` with exactly one `<url>` entry — the site root — not one per page.
+
+This isn't an oversight. `index.html` uses `routerMode: 'history'`, and GitHub Pages has no
+server-side rewrite support, so every URL except the bare root is served via the `404.html`
+fallback trick — with a genuine HTTP 404 status, even though the page renders correctly once
+Docsify's JS boots. Google's own documentation is explicit that a 4xx status is a hard stop for
+indexing regardless of rendered content (see
+[HTTP status codes and network/DNS errors](https://developers.google.com/search/docs/crawling-indexing/http-network-errors)).
+Listing all pages would just be dozens of confirmed-dead entries in Search Console's coverage
+report — decided 2026-08-25 to keep the sitemap to the one URL that's actually indexable as
+things stand, rather than that.
+
+If a future change gives individual pages a real HTTP 200 (e.g. a build step that pre-renders
+each route to a static file, discussed but not implemented as of this decision — see
+`scripts/generate_sitemap.py`'s own docstring), `generate_sitemap.py`'s scope should expand back
+to all pages.
+
 ## Checking it worked
 
 `https://tedsluis.github.io/opencontrolpixelbudspro2/` — GitHub Pages builds typically go live

scripts/generate_sitemap.py

@@ -1,22 +1,25 @@
 #!/usr/bin/env python3
-"""Generates sitemap.xml for the Docsify site (history-mode, real path-based URLs).
-
-Reuses the exact file set `ensure_footers.py`/`lint_docs.py` already treat as
-"doc pages" (`footer_files()` — every tracked `.md` file except `_sidebar.md`,
-`CLAUDE.md`, and `AUDIT_REPORT_*.md`, the last excluded by
-`all_markdown_files()`) so this can't silently drift from what the footer
-system considers a real page.
-
-Each URL uses `docsify_route()` (same helper the footer URLs use) so the
-sitemap always matches whatever path scheme `index.html`'s routerMode
-actually serves — history mode, no `#`. `README.md` maps to the site root
-(`BASE_URL/`), matching `index.html`'s `homepage: 'README.md'`.
-
-`<lastmod>` is each file's last commit date (`git log -1 --format=%cI`) — a
-full, unshallowed checkout is required for this to be accurate (see
-`.github/workflows/update-sitemap.yml`'s `fetch-depth: 0`); a file with no
-resolvable git history (e.g. never committed yet) is emitted without one
-rather than guessing.
+"""Generates sitemap.xml for the Docsify site — the site root only.
+
+Root-only by deliberate choice (2026-08-25), not an oversight: index.html
+serves routerMode: 'history' via GitHub Pages' 404.html fallback trick (no
+server-side rewrite support there), which means every URL except the bare
+site root returns a genuine HTTP 404 status — confirmed live by curl against
+all 69 pages. Per Google's own documentation, a 4xx status is a hard stop:
+"any content Google receives from URLs that return a 4xx status code is
+ignored" (developers.google.com/search/docs/crawling-indexing/http-network-errors).
+A sitemap listing all 69 pages would just be 68 confirmed dead entries in
+Search Console's coverage report — this lists only the one URL that's
+actually indexable as things stand.
+
+If a future change makes individual pages return real 200s (e.g. build-time
+pre-rendering to static files per route), this script's scope should expand
+back to all pages — see MAINTAINING_DOCS_SITE.md and git history around
+2026-08-25 for that discussion and the options considered.
+
+`<lastmod>` is README.md's own last commit date (`git log -1 --format=%cI`) —
+a full, unshallowed checkout is required for this to be accurate (see
+`.github/workflows/update-sitemap.yml`'s `fetch-depth: 0`).
 
 Usage: ./scripts/generate_sitemap.py
 """
@@ -29,7 +32,7 @@
 from xml.sax.saxutils import escape
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from lint_docs import REPO_ROOT, docsify_route, footer_files  # noqa: E402
+from lint_docs import REPO_ROOT  # noqa: E402
 
 BASE_URL = "https://tedsluis.github.io/opencontrolpixelbudspro2"
 
@@ -46,34 +49,25 @@ def last_commit_date(path: Path) -> str | None:
     return date or None
 
 
-def page_url(path: Path) -> str:
-    rel = path.relative_to(REPO_ROOT).as_posix()
-    if rel == "README.md":
-        return f"{BASE_URL}/"
-    return f"{BASE_URL}/{docsify_route(rel)}"
-
-
 def main() -> int:
-    files = sorted(footer_files(), key=lambda p: p.relative_to(REPO_ROOT).as_posix())
+    readme = REPO_ROOT / "README.md"
+    lastmod = last_commit_date(readme)
 
     lines = [
         '<?xml version="1.0" encoding="UTF-8"?>',
         '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        "  <url>",
+        f"    <loc>{escape(BASE_URL)}/</loc>",
     ]
-    for path in files:
-        url = page_url(path)
-        lastmod = last_commit_date(path)
-        lines.append("  <url>")
-        lines.append(f"    <loc>{escape(url)}</loc>")
-        if lastmod:
-            lines.append(f"    <lastmod>{lastmod}</lastmod>")
-        lines.append("  </url>")
+    if lastmod:
+        lines.append(f"    <lastmod>{lastmod}</lastmod>")
+    lines.append("  </url>")
     lines.append("</urlset>")
     lines.append("")
 
     out_path = REPO_ROOT / "sitemap.xml"
     out_path.write_text("\n".join(lines), encoding="utf-8")
-    print(f"Wrote {out_path.relative_to(REPO_ROOT)} with {len(files)} URLs")
+    print(f"Wrote {out_path.relative_to(REPO_ROOT)} with 1 URL (root only — see this script's docstring)")
     return 0