Research: mkdocs nav restructure for 631 ADRs (2026-05-31)¶
Context: project-modernization-audit queue item #13 — "Restructure mkdocs nav for 700+ ADRs by decade + auto-generated by-tag indexes". The fork's existing mkdocs.yml carved out the entire ADR tree from nav: because enumerating ~600 files in a flat list was unmanageable; the trade-off was that ADRs were invisible in the material-theme left rail.
Inputs¶
- 631 ADR files under
docs/adr/*.md(excluding0000-template.md). - 599-row
docs/adr/_index_fragments/_order.txtdriving the README render. - 611 ADRs with a
- **Tags**:front-matter line, 2 with bareTags:. - 442 distinct normalised tags across the corpus.
Bucketing distribution¶
Per-hundred bucket counts (ADR ID range → ADR count):
| Bucket | Count | Dominant theme |
|---|---|---|
| 0000-0099 | 42 | Foundation, build, golden gate |
| 0100-0199 | 99 | Doc-substance, fragments, ports |
| 0200-0299 | 85 | GPU coverage, tiny-AI scaffolding |
| 0300-0399 | 93 | vmaf-tune, corpus ingestion, CI gates |
| 0400-0499 | 82 | GPU parity, ffmpeg patches, MCP runtime |
| 0500-0599 | 90 | Multi-vendor GPU, container, audits |
| 0600-0699 | 85 | Saliency, predictor v2/v3, signal mix |
| 0700-0799 | 48 | VMAFx rebrand, Go/Rust/C++23, k8s |
| 0800-0899 | 7 | Backfill / pending sweeps |
The dominant-theme labels are derived by sampling 10–20 titles per bucket; they are editorial and live in LABELS inside generate-adr-nav.sh.
Top tags (>= 30 ADRs)¶
fork-local (303), ai (164), build (107), gpu (103), ci (97), cuda (88), docs (86), vulkan (85), vmaf-tune (77), sycl (65), hip (59), feature-extractor (59), dnn (59), tooling (49), cli (46), ffmpeg (44), training (44), agents (41), simd (39), corpus (38), mcp (36), performance (36), tiny-ai (34), security (32), correctness (31), testing (31), bugfix (30), onnx (30).
The long tail consists of metric-specific tags (adm, vif, cambi, ssimulacra2), backend specifiers (avx2, neon, metal, coreml), process tags (audit, deferral, breaking-change), and ADR-specific cross-references (adr-0100, adr-0108).
mkdocs-material nav behaviour¶
navigation.sections + navigation.expand already enabled in mkdocs.yml. Collapsible sub-sections render as expandable left-rail groups; the per-hundred buckets nest correctly under - ADRs: without new theme features.
navigation.indexes is not enabled — Overview: adr/README.md is written explicitly, which is the documented pattern for theme-version compatibility.
Build cost¶
| Configuration | mkdocs build --strict wall time |
|---|---|
| Baseline (ADRs carved out) | ~28 s |
| After restructure (631 ADRs + 443 by-tag pages in nav) | ~100 s |
The 3.5x slowdown is the price of actually rendering the 1074 extra pages into the nav. Acceptable — the docs build runs once per PR and is not on any developer hot path.
Drift detection¶
Both generator scripts ship --check modes that diff in-tree output against a freshly-rendered run and exit non-zero on drift. A future PR can wire them into .github/workflows/docs.yml to fail fast when an ADR lands without a regenerated nav / by-tag index.
Open items¶
- Bucket labels for 0800s / 0900s are placeholder
Misc(only 7 entries currently); fill in once those buckets have enough ADRs to read a theme off. - The
By taggroup lists 442 entries — long but acceptable; a future refinement could surface only tags with >= 5 ADRs in the nav and leave the long tail to theOverviewindex. Not done now — keeping parity with the task spec ("Add each to nav").