enforce nav order for implementation domains and system levels

Author: CameronBrooks11

_data/sources.json

@@ -7,6 +7,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "implementation-domains/breads",
+            "nav_order": 1,
             "redirect_from": [
                 "/breads/",
                 "/breads"
@@ -23,6 +24,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "implementation-domains/froots",
+            "nav_order": 2,
             "redirect_from": [
                 "/froots/",
                 "/froots"
@@ -39,6 +41,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "implementation-domains/protins",
+            "nav_order": 3,
             "redirect_from": [
                 "/protins/",
                 "/protins"
@@ -55,6 +58,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "implementation-domains/sugirs",
+            "nav_order": 4,
             "redirect_from": [
                 "/sugirs/",
                 "/sugirs"
@@ -71,6 +75,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "system-levels/slice",
+            "nav_order": 1,
             "redirect_from": [
                 "/slice/",
                 "/slice"
@@ -87,6 +92,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "system-levels/loaf",
+            "nav_order": 2,
             "redirect_from": [
                 "/loaf/",
                 "/loaf"
@@ -103,6 +109,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "system-levels/batch",
+            "nav_order": 3,
             "redirect_from": [
                 "/batch/",
                 "/batch"
@@ -119,6 +126,7 @@
             "ref": "main",
             "subdir": "docs",
             "mount": "system-levels/oven",
+            "nav_order": 4,
             "redirect_from": [
                 "/oven/",
                 "/oven"

scripts/ensure_front_matter.py

@@ -25,6 +25,7 @@
 argv[1]            : Path to the imported project root (mount directory)
 Env.PROJECT_TITLE  : Optional project display name (defaults to directory name)
 Env.REDIRECT_FROM  : Optional JSON array or string for redirect_from on hub
+Env.NAV_ORDER      : Optional integer for nav_order on hub
 
 Outputs
 -------
@@ -135,12 +136,15 @@ def _normalize_redirect_from(
     return sorted(out)
 
 
-def ensure_hub_index(root: Path, project_title: str, redirect_from_env: str) -> Path:
+def ensure_hub_index(
+    root: Path, project_title: str, redirect_from_env: str, nav_order_env: str
+) -> Path:
     """
     Create or normalize the hub page at <root>/index.md.
 
     Forces canonical title and section semantics. Merges redirect_from entries
     from REDIRECT_FROM env to support legacy slugs via jekyll-redirect-from.
+    Sets nav_order if provided in NAV_ORDER env.
     """
     hub = root / "index.md"
     if hub.exists():
@@ -155,6 +159,13 @@ def ensure_hub_index(root: Path, project_title: str, redirect_from_env: str) ->
     fm.pop("parent", None)
     fm.pop("grand_parent", None)
 
+    # Set nav_order if provided
+    if nav_order_env and nav_order_env.strip():
+        try:
+            fm["nav_order"] = int(nav_order_env.strip())
+        except ValueError:
+            pass  # Ignore invalid nav_order values
+
     redirects = _normalize_redirect_from(redirect_from_env, fm.get("redirect_from"))
     if redirects:
         fm["redirect_from"] = redirects
@@ -243,8 +254,9 @@ def main(argv: list[str]) -> int:
     root = Path(argv[1]).resolve()
     project_title = os.environ.get("PROJECT_TITLE", root.name).strip() or root.name
     redirect_from_env = os.environ.get("REDIRECT_FROM", "")
+    nav_order_env = os.environ.get("NAV_ORDER", "")
 
-    hub = ensure_hub_index(root, project_title, redirect_from_env)
+    hub = ensure_hub_index(root, project_title, redirect_from_env, nav_order_env)
 
     for path in root.rglob("*"):
         process_page(root, hub, project_title, path)

scripts/import_sources.sh

@@ -9,7 +9,7 @@
 #     * Rsync the selected subtree into the local .mount path
 #       - Respects per-source "exclude" globs and per-repo ".indexignore"
 #     * Normalize front matter for Just the Docs via ensure_front_matter.py
-#       - Passes PROJECT_TITLE and REDIRECT_FROM (JSON) env vars
+#       - Passes PROJECT_TITLE, REDIRECT_FROM (JSON), and NAV_ORDER env vars
 #
 # Inputs:
 #   sources.json entries:
@@ -21,6 +21,7 @@
 #     - mount           : destination mount path in this repo
 #     - exclude[]       : optional rsync exclude patterns
 #     - redirect_from[] : optional legacy slugs (or "redirects[]" for bw-compat)
+#     - nav_order       : optional integer for navigation ordering
 #
 # Requirements: bash, git, jq, rsync
 # Safe defaults: set -euo pipefail, strict quoting, basic path sanitization.
@@ -109,7 +110,8 @@ jq -c '.sources[]' "$MANIFEST" | while IFS= read -r row; do
   echo "::group::Normalize front matter for ${mount}"
   # Accept either "redirect_from" or legacy "redirects"
   redirect_from_json="$(jq -c '.redirect_from? // .redirects? // []' <<<"$row")"
-  PROJECT_TITLE="$title" REDIRECT_FROM="$redirect_from_json" \
+  nav_order="$(jq -r '.nav_order? // ""' <<<"$row")"
+  PROJECT_TITLE="$title" REDIRECT_FROM="$redirect_from_json" NAV_ORDER="$nav_order" \
     python3 "${ROOT}/scripts/ensure_front_matter.py" "$MOUNT_ABS"
   echo "::endgroup::"
 done