docs_nav.py
Give the rendered site one curated reading order.
Overview
Give the rendered site one curated reading order.
The generator ranks the guide list by keyword buckets, which is a reasonable default and a poor journey: install and configure material was scattered, and a reader finishing one page got no pointer to the next. This pass owns the order in one place:
* the landing page's Guides section is rebuilt into curated buckets
(get it running first, then the two kinds of depth: research, and this
project's own engineering log) — and because the sidebar shim mirrors the
landing page's buckets, the sidebar follows automatically,
* every page on the journey gets a prev/next pager, so there is always a
next page and it is always the right one,
* each guide's hero eyebrow names its bucket instead of the generic
"Guide".
The buckets and the journey are the same list, so they cannot drift apart. A guide added without a place in it fails the build here, on purpose: the author decides where it belongs, or this pass would silently undo the point of having a curated order.
Run from the repo root, after docs_start.py (start.html must exist to lead the journey) and before docs_graph.py (whose sidebar shim reads the landing page's buckets as rebuilt here).
flowchart TD add_pagers --> fail add_pagers --> page_title
API
Ffail(msg: str) -> int
Print an error message to stderr prefixed with "docs_nav: " and return 1.
add_pagers, curate_indexFpage_title(slug: str) -> str
Extract the page title from the <title> tag in an HTML file by path slug; return the slug itself if no title is found.
add_pagersFcurate_index(index: Path) -> int | None
Rebuild the Guides section into the journey's buckets.
main · calls failFadd_pagers() -> int | None
Inject previous/next navigation cards before </main> on each journey page, updating the eyebrow label to the guide bucket name (except on the start page); do nothing if pager already present.
main · calls fail, page_titleFmain() -> int
Check that the rendered site exists, rebuild the landing-page guides into journey buckets, inject previous/next pagers into journey pages, report results.
add_pagers, curate_index