Various fixes

Author: mckeea

.github/scripts/build/apply_cached_intros.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Apply cached intros/keywords from .llm_cache/ into .qmd frontmatter (no API).
+
+Run before group_docs_by_category - the cache is keyed by the original path.
+Usage: apply_cached_intros.py [DOCS_DIR]   # default: DOCS
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# repo root is three levels up from .github/scripts/build
+SCRIPT_DIR = Path(__file__).resolve().parent
+SCRIPTS_ROOT = SCRIPT_DIR.parent
+sys.path.insert(0, str(SCRIPTS_ROOT))
+
+from helpers.qmd_utils import find_qmd_files  # noqa: E402
+from helpers.file_updater import apply_all_updates  # noqa: E402
+
+ROOT_DIR = (SCRIPT_DIR / "../../..").resolve()
+CACHE_DIR = (ROOT_DIR / ".llm_cache").resolve()
+# skip non-doc dirs, same set as update_documentation.py
+BLACKLISTED_DIRS = {
+    "templates",
+    "includes",
+    "theme",
+    "_meta",
+    "assets",
+    "_site",
+    ".quarto",
+}
+
+
+def main() -> int:
+    docs_arg = sys.argv[1] if len(sys.argv) > 1 else "DOCS"
+    input_dir = Path(docs_arg).resolve()
+
+    if not input_dir.is_dir():
+        print(f"[apply_cached_intros] '{input_dir}' is not a directory - skipping")
+        return 0
+
+    if not CACHE_DIR.is_dir():
+        print(f"[apply_cached_intros] no cache at {CACHE_DIR} - nothing to apply")
+        return 0
+
+    # cache keys start with the DOCS dir name, so resolve against its parent
+    lookup_root = input_dir.parent
+
+    qmd_files = set(find_qmd_files(input_dir, BLACKLISTED_DIRS))
+    if not qmd_files:
+        print(f"[apply_cached_intros] no .qmd files under {input_dir}")
+        return 0
+
+    stats = apply_all_updates(
+        qmd_files,
+        CACHE_DIR,
+        dry_run=False,
+        root_dir=lookup_root,
+        apply_versions=False,
+    )
+
+    # don't fail the build over a frontmatter glitch
+    if stats.get("errors"):
+        print(f"[apply_cached_intros] done, with {len(stats['errors'])} error(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/build/build-docs.sh

@@ -31,6 +31,10 @@ step() {
   _STEP_PREV=$now; _STEP_NAME="$*"
 }
 
+# Apply cached intros/keywords before the rename - the cache is keyed by original path.
+echo "Injecting cached intros & keywords (no API)..."
+python3 .github/scripts/build/apply_cached_intros.py DOCS
+
 step "[1/6] Copying DOCS to origin_DOCS..."
 mv DOCS origin_DOCS
 

.github/scripts/helpers/file_updater.py

@@ -38,21 +38,25 @@ def apply_all_updates(
     cache_dir: Path,
     dry_run: bool = False,
     root_dir: Path | None = None,
+    apply_versions: bool = True,
 ) -> dict:
     """Merge all cached updates into each .qmd's frontmatter, writing each file once.
     Returns a stats dict (files_updated, intros_applied, versions_applied, errors).
 
     root_dir matters: cache keys are repo-relative, so absolute paths in
     files_to_update are rewritten to that form before lookup — without it every
-    lookup silently misses. dry_run shows the changes without writing."""
+    lookup silently misses. dry_run shows the changes without writing.
+
+    apply_versions=False does intros/keywords only, leaving version/date alone -
+    the build step uses this since fill_version.py handles versions there."""
     print("\n" + "=" * 70)
     print("📝 Applying All Cached Updates to .qmd Files")
     print("=" * 70)
 
     if dry_run:
         print("[DRY RUN] Showing updates but NOT modifying files\n")
 
-    versions_metadata = load_versions_metadata(cache_dir)
+    versions_metadata = load_versions_metadata(cache_dir) if apply_versions else {}
 
     stats = {
         "files_updated": 0,
@@ -100,7 +104,7 @@ def apply_all_updates(
 
             # 2. Apply version updates if available
             filepath_str = str(lookup_path)
-            if filepath_str in versions_metadata:
+            if apply_versions and filepath_str in versions_metadata:
                 version_data = versions_metadata[filepath_str]
                 new_version = version_data.get("current_version")
                 if new_version:

.github/workflows/deploy-docs.yml

@@ -100,12 +100,6 @@ jobs:
             git push origin HEAD
           fi
 
-      # Hotfix: install chrome into the job's HOME so the Typst diagram render
-      # finds it (container jobs set HOME=/github/home). Drop once the rebuilt
-      # image bakes XDG_DATA_HOME in.
-      #- name: Ensure headless Chrome for diagram rendering
-      #  run: quarto install chrome-headless-shell
-
       - name: Build Docs
         run: .github/scripts/build/build-docs.sh