feature: render configuration per doc-type added

Author: mckeea

.github/scripts/build/apply_cached_intros.py

@@ -15,8 +15,9 @@
 SCRIPTS_ROOT = SCRIPT_DIR.parent
 sys.path.insert(0, str(SCRIPTS_ROOT))
 
-from helpers.qmd_utils import find_qmd_files  # noqa: E402
+from helpers.qmd_utils import find_qmd_files, read_qmd_frontmatter  # noqa: E402
 from helpers.file_updater import apply_all_updates  # noqa: E402
+from helpers.doc_types import element_off  # noqa: E402
 
 ROOT_DIR = (SCRIPT_DIR / "../../..").resolve()
 CACHE_DIR = (ROOT_DIR / ".llm_cache").resolve()
@@ -52,6 +53,20 @@ def main() -> int:
         print(f"[apply_cached_intros] no .qmd files under {input_dir}")
         return 0
 
+    # Skip types that take neither intro nor keywords (dashboard) so nothing is
+    # injected, not even into the origin_DOCS copy. They come as one bundle,
+    # hence the "both off" check — split it if a type ever wants only one.
+    def _wants_intro(qmd: Path) -> bool:
+        fm, _ = read_qmd_frontmatter(qmd)
+        dtype = fm.get("type")
+        return not (element_off(dtype, "keywords") and element_off(dtype, "description"))
+
+    kept = {q for q in qmd_files if _wants_intro(q)}
+    skipped = len(qmd_files) - len(kept)
+    if skipped:
+        print(f"[apply_cached_intros] skipping {skipped} file(s) whose type omits intros/keywords")
+    qmd_files = kept
+
     stats = apply_all_updates(
         qmd_files,
         CACHE_DIR,

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

@@ -127,6 +127,10 @@ cp _site/sitemap.xml.bkp _site/sitemap.xml
 rm -f _site/sitemap.xml.bkp
 mv _site/llms.txt.bkp _site/llms.txt
 
+# Drop .llms.md for llms-off types (dashboard), before the llm sitemap so it
+# falls back to the HTML URL.
+python3 ../.github/scripts/build/strip_llms_sidecars.py . _site
+
 # Remove non-browsable links from sitemap.xml and llms.txt
 python3 ../.github/scripts/build/remove_non_browsable.py _site/sitemap.xml
 python3 ../.github/scripts/build/remove_non_browsable.py --format llms _site/llms.txt

.github/scripts/build/fill_version.py

@@ -21,6 +21,7 @@
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))  # .github/scripts
 from helpers.json_io import load_json_or_empty
+from helpers.doc_types import element_off
 
 VERSIONS_FILE = ".llm_cache/versions.json"
 
@@ -83,6 +84,10 @@ def main():
             continue
         _, end = bounds
 
+        # version-off types keep their own `version:` header, if any; don't touch.
+        if element_off(fm_value(lines, end, "type"), "version"):
+            continue
+
         src = fm_value(lines, end, "original-filename")
         mj = major_from_name(src) if src else None
         if mj is None:

.github/scripts/build/inject_changelog.py

@@ -11,6 +11,10 @@
 pf.elements.RAW_FORMATS.add("typst")
 pf.elements.RAW_FORMATS.add("pdf")
 
+# honour `changelog: false` from doc-types.yml
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+from helpers.doc_types import element_off
+
 CHANGE_LOG_PATH = os.path.abspath(
     os.path.join(os.path.dirname(__file__), "../../../.llm_cache/change_logs.json")
 )
@@ -166,6 +170,10 @@ def get_input_file(doc):
 
 def add_changelog(doc):
     """Main filter function that adds changelog to the document"""
+    # changelog-off types (dashboard) get no Change Log
+    if element_off(doc.get_metadata("type"), "changelog"):
+        return doc
+
     current_file = get_input_file(doc)
     if not current_file:
         return doc

.github/scripts/build/strip_llms_sidecars.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Delete the .llms.md sidecar for docs whose type has `llms` off (dashboards).
+
+`llms-txt: true` drops an <name>.llms.md next to every page and has no per-doc
+opt-out, so we delete it after render. DOCS/<rel>.qmd -> _site/<rel>.llms.md.
+
+Run before generate_llm_sitemap.py (it falls back to the HTML URL when the file
+is gone). Non-browsable docs already lose their llms.txt/sitemap entry via
+remove_non_browsable.py; this just clears the orphan file. A browsable llms-off
+type would also need its llms.txt entry stripped — deal with that if it happens.
+
+Usage: strip_llms_sidecars.py <docs_dir> <site_dir>   # e.g. . _site
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR.parent))  # .github/scripts
+
+from helpers.doc_types import element_off  # noqa: E402
+from helpers.qmd_utils import read_qmd_frontmatter, find_qmd_files  # noqa: E402
+
+SKIP_DIRS = {"_site", ".quarto", "_meta", "templates", "theme", "includes"}
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("usage: strip_llms_sidecars.py <docs_dir> <site_dir>", file=sys.stderr)
+        return 2
+    docs_dir = Path(sys.argv[1]).resolve()
+    site_dir = Path(sys.argv[2]).resolve()
+
+    removed = 0
+    for qmd in find_qmd_files(docs_dir, SKIP_DIRS):
+        fm, _ = read_qmd_frontmatter(qmd)
+        if not element_off(fm.get("type"), "llms"):
+            continue
+        sidecar = site_dir / qmd.relative_to(docs_dir).with_suffix(".llms.md")
+        if sidecar.exists():
+            sidecar.unlink()
+            removed += 1
+            print(f"  • removed {sidecar.relative_to(site_dir)}")
+
+    print(f"[strip_llms_sidecars] removed {removed} .llms.md sidecar(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/build/strip_unknown_frontmatter.py

@@ -24,6 +24,7 @@
 sys.path.insert(0, str(SCRIPTS_ROOT))
 
 from helpers.qmd_utils import read_qmd_frontmatter, write_qmd_frontmatter  # noqa: E402
+from helpers.doc_types import config_for, DEFAULT_FORMATS  # noqa: E402
 
 
 ALLOWLIST = {
@@ -36,6 +37,9 @@
     "version",
     "keywords",
     "original-filename",
+    # Kept (not stripped) so fill_version / inject_changelog / strip_llms can
+    # read it downstream.
+    "type",
 }
 
 EXCLUDED_DIRS = {"templates", "theme", "includes", "_meta", "_site", ".quarto"}
@@ -46,17 +50,61 @@ def is_excluded(qmd_path: Path, source_root: Path) -> bool:
     return any(part in EXCLUDED_DIRS for part in rel_parts)
 
 
+def apply_doc_type(fm: dict) -> None:
+    """Apply the type config to `fm` in place.
+
+    Only OFF toggles do anything (ON == the default), so an untyped doc is
+    untouched. The frontmatter toggles are done here; version/changelog/llms are
+    handled later by fill_version / inject_changelog / strip_llms_sidecars, which
+    read `type` themselves.
+    """
+    cfg = config_for(fm.get("type"))
+    els = cfg["elements"]
+
+    # OFF actions only (ON == existing default == leave frontmatter untouched).
+    if els["toc"] is False:
+        fm["toc"] = False
+    if els["number-sections"] is False:
+        fm["number-sections"] = False
+    if els["code"] is False:
+        fm["echo"] = False  # hides code source; Quarto tags the cell .hidden
+    if els["contact"] is False:
+        fm["contact"] = False  # honoured by filters/inject_contact_info.lua
+    if els["keywords"] is False:
+        fm.pop("keywords", None)  # no project-level keywords default to leak now
+    if els["description"] is False:
+        fm.pop("description", None)
+
+    # style keys + code-fold off when code is off (project defaults it on, which
+    # would leave fold triangles on hidden cells).
+    html_opts = dict(cfg["style"])
+    if els["code"] is False:
+        html_opts["code-fold"] = False
+
+    # A doc `format:` block replaces the project's whole format list (Quarto's
+    # one non-merging key), so only write it when we're restricting formats or
+    # setting html options — never for the default.
+    formats = cfg["formats"]
+    if formats != DEFAULT_FORMATS or html_opts:
+        fm["format"] = {
+            f: (dict(html_opts) if f == "html" and html_opts else "default")
+            for f in formats
+        }
+
+
 def strip_one(qmd_path: Path) -> tuple[bool, list[str]]:
     """Return (changed, dropped_field_names)."""
     yaml_data, lines = read_qmd_frontmatter(qmd_path)
     if not yaml_data or not lines:
         return False, []
 
     dropped = sorted(k for k in yaml_data.keys() if k not in ALLOWLIST)
-    if not dropped:
+    cleaned = {k: v for k, v in yaml_data.items() if k in ALLOWLIST}
+    apply_doc_type(cleaned)
+
+    if cleaned == yaml_data:  # nothing dropped and no type deviations -> no-op
         return False, []
 
-    cleaned = {k: v for k, v in yaml_data.items() if k in ALLOWLIST}
     write_qmd_frontmatter(qmd_path, cleaned, lines)
     return True, dropped
 

.github/scripts/doc-types.yml

@@ -0,0 +1,48 @@
+# Single source of truth for DOCS document *types*.
+# A document's `type:` frontmatter field selects one of these; the
+# build then keeps/omits elements and picks output formats accordingly.
+# Read via helpers/doc_types.py by:
+#   - validate_qmd_files.py        (allowed values for `type:`)
+#   - build/strip_unknown_frontmatter.py  (applies element toggles + formats)
+#   - build/fill_version.py        (skips versioning when version is off)
+#   - build/strip_llms_sidecars.py (deletes .llms.md when llms is off)
+#
+# Add / edit types ONLY here. Fields per entry:
+#   name      (required) value authors put in `type:`; lowercase kebab-case.
+#   elements  (optional) on/off toggles; any omitted toggle defaults to TRUE (on).
+#             Known toggles: toc, keywords, description, version, changelog,
+#             contact, code, number-sections, llms.
+#   formats   (optional, default [html, typst, gfm]) output formats to render.
+#   style     (optional) extra keys merged into the HTML format block (e.g. page-layout, css).
+#
+# `document` is the library default and MUST exist. Because every toggle's ON
+# state equals the pipeline's existing default, the `document` type is a no-op:
+# a doc with no `type:` renders exactly as before this feature existed.
+types:
+  - name: document              # the library default — restates every default explicitly
+    elements:
+      toc: true
+      keywords: true
+      description: true
+      version: true
+      changelog: true
+      contact: true
+      code: true
+      number-sections: true
+      llms: true
+    formats: [html, typst, gfm]
+
+  - name: dashboard             # interactive OJS pages (e.g. CDSE migration dashboard)
+    elements:
+      toc: false
+      keywords: false
+      description: false
+      version: false
+      changelog: false
+      contact: false
+      code: false
+      number-sections: false
+      llms: false
+    formats: [html]
+    style:
+      page-layout: full