docs: fail the build on pages missing from the nav

MkDocs (--strict with validation.omitted_files: warn) failed the build for
a page on disk that the nav omitted; Zensical builds it as unreachable
orphan HTML. Validate both directions of nav/page drift in build_config
with one nav walker, using the same scheme-based external-link test as
llms_txt so a scheme-only nav entry (mailto:) cannot be misread as a page
path. The generated api/ tree is exempt from the orphan check: its nav is
spliced in from the same generator that writes the files.

Author: maxisbey

scripts/docs/build_config.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 
 # Both scripts live in this directory, which Python puts on sys.path[0] when
@@ -21,23 +22,44 @@
 
 ROOT = Path(__file__).parent.parent.parent
 
+# A scheme-prefixed nav value (https:, mailto:, ...) is an external link, not
+# a page path (same classifier as llms_txt.py; a `://` test would misread
+# scheme-only URIs as pages).
+_EXTERNAL = re.compile(r"[a-zA-Z][a-zA-Z0-9+.-]*:")
 
-def _missing_nav_pages(nav: list, docs_dir: Path) -> list[str]:
-    """Collect nav page references that don't exist under the docs dir.
 
-    Zensical (0.0.48) ships a nav entry for a nonexistent page as a broken
-    link without any diagnostic, even under --strict — MkDocs aborted the
-    build. Validating here keeps that guarantee: the concrete config never
-    leaves this script referencing a page that isn't there.
-    """
-    missing: list[str] = []
+def _nav_pages(nav: list) -> set[str]:
+    """Collect every local page reference in the nav (external links excluded)."""
+    pages: set[str] = set()
     for entry in nav:
         value = next(iter(entry.values())) if isinstance(entry, dict) else entry
         if isinstance(value, list):
-            missing.extend(_missing_nav_pages(value, docs_dir))
-        elif "://" not in value and not (docs_dir / value).is_file():
-            missing.append(value)
-    return missing
+            pages |= _nav_pages(value)
+        elif not _EXTERNAL.match(value):
+            pages.add(value)
+    return pages
+
+
+def _validate_nav(nav: list, docs_dir: Path) -> None:
+    """Fail on nav/page drift in either direction.
+
+    Zensical (0.0.48) ships a nav entry for a nonexistent page as a broken
+    link without any diagnostic even under --strict, and publishes a page
+    that no nav entry reaches as unreachable orphan HTML; MkDocs aborted the
+    build on both (--strict with `validation.omitted_files: warn`).
+    Validating here keeps those guarantees. The generated `api/` tree is
+    exempt from the orphan check: its nav is spliced in from the same
+    generator that writes the files, so it cannot drift.
+    """
+    pages = _nav_pages(nav)
+    if missing := sorted(page for page in pages if not (docs_dir / page).is_file()):
+        raise SystemExit(f"build_config: nav references pages that don't exist under docs/: {missing}")
+    # Dot-directories (e.g. `.overrides` theme files) are not pages: the site
+    # builder ignores them, so the orphan check must too.
+    relative = (page.relative_to(docs_dir) for page in docs_dir.rglob("*.md"))
+    on_disk = {page.as_posix() for page in relative if not any(part.startswith(".") for part in page.parts)}
+    if orphaned := sorted(page for page in on_disk - pages if not page.startswith("api/")):
+        raise SystemExit(f"build_config: pages under docs/ that no nav entry reaches: {orphaned}")
 
 
 def build_config() -> None:
@@ -53,8 +75,7 @@ def build_config() -> None:
     else:
         raise SystemExit("build_config: no 'API Reference' entry found in mkdocs.yml nav")
 
-    if missing := _missing_nav_pages(config["nav"], ROOT / "docs"):
-        raise SystemExit(f"build_config: nav references pages that don't exist under docs/: {missing}")
+    _validate_nav(config["nav"], ROOT / "docs")
 
     output = ROOT / "mkdocs.gen.yml"
     output.write_text(yaml.safe_dump(config, sort_keys=False, allow_unicode=True), encoding="utf-8")