[gtauzin]

Why

docs/hooks.py was 2678 lines behind five MkDocs event hooks. Two of them did work that has nothing to do with rendering a page:

• on_pre_build reads src/, writes docs/pages/api/*.md, exports the marimo notebooks — and ignores its config argument entirely
• on_post_build reads site/, writes markdown back into it — using config for two directory strings

Neither imports a MkDocs type. They are file-in/file-out programs wearing a hook as a costume, and the costume cost real things: the only way to run either was a full mkdocs build, so they lived in the slowest test tier for logic needing no theme, no server and no markdown; the generated .md was an intermediate nobody could produce on demand; and the discovery layer was reinvented independently by four generated repos before the template consolidated one.

What changed

~1000 lines moved into three modules that import nothing from mkdocs:

module	contents
docs/_api_pages.py	discovery layer + API page generation
docs/_notebooks.py	marimo export + content-hash cache (examples only)
docs/_markdown_export.py	HTML→markdown conversion + llms.txt

Each has a main() and runs standalone. New nox -s build_steps runs them without a docs build.

The hooks stay as adapters. Deleting them would break the documented preview workflow — mkdocs.yml watches src so adding a class appears without restarting mkdocs serve, and that only works because on_pre_build regenerates on every rebuild.

Verification

Byte-identity. The generated API pages are identical before and after, under both include_examples values. The one site file that differs is proven nondeterministic by a control (two builds of the same code differ — marimo embeds a per-export UUID).

A real leak fixed. mkdocs treats every non-page file under docs_dir as a static asset, so it was publishing the build tooling's source and bytecode to the docs site. Already true of hooks.py; splitting it made it four modules. exclude_docs now covers *.py and __pycache__/.

Cache guarantee kept. Two caches moved with their functions, so on_config calls _api_pages.reset_caches() — a global statement cannot rebind another module's globals. The registration test was scanning only the hooks module, so it had silently narrowed to "every cache that stayed behind" while still passing; it now scans every module the hooks load, and is mutation-tested (removing the reset fails it, naming both caches).

Checked against a live server. Adding a class to src/ and retitling a notebook's __gallery__ both appear without a restart.

• 333 fast tests pass · 9 slow tests pass (4 pre-existing skips) · prek clean
• mkdocs build --strict clean on both variants

Lint config narrowed

docs/**/* split into two entries. The hooks keep their unused-argument exemptions (they implement mkdocs' signatures); the extracted steps get only T201/PLW0603 — no blanket ARG exemption, because they implement no imposed signature. That immediately caught a genuinely unused parameter with examples disabled.

Not done here (deliberately)

• The print("[hooks] …") prefix still says [hooks] from _api_pages — a rename, excluded from a move
• docs_examples could use docs_dir / "examples" instead of project_root / "docs" / "examples" — more correct, but a behaviour change
• Pre-existing bug found, not fixed: editing a source file under mkdocs serve triggers a rebuild loop (_generate_api_pages writes into a watched path). Symmetric control: baseline +18 rebuilds, this branch +19 — unchanged by this PR

Downstream

Fan-out to the seven generated repos follows release. hooks.py is Tier 1, but Dynamic Reclassification promotes a locally-edited Tier 1 file to Tier 2, so copier update merges rather than overwrites — a one-file-into-four split against a fork is not a case the tiering was designed for. Establish each repo's actual fork status first (render the template with that repo's .copier-answers.yml and diff; cross-repo md5 comparison proves nothing, since the template interpolates {{ package_name }} 20 times).