feat(site): a header on every page, and navigation for the docs (phase 5)

[TMHSDigital]

The site had one navigation device: a wrapping row of links at the top of each page. METHODOLOGY and PLAN are long enough that moving around them meant scrolling and searching the page. This is the first of three phases that give the site real structure without changing its voice or its rules (no external requests, docs rendered from the commit, parity with the Python).

What a reader gets

• A header on every page: Calculator, Docs, Example report, GitHub, and a theme toggle (auto, light, dark, remembered).
• On doc pages:
  • a grouped sidebar (Using plumbline, Project);
  • an "On this page" list that highlights the section in view;
  • a # link on every h2 and h3 that copies itself;
  • previous and next links;
  • "Edit on GitHub";
  • copy buttons on code blocks.
• Layout by width:
  • 80rem and wider: three columns.
  • 64 to 80rem: sidebar plus a collapsible contents list.
  • Narrower: both collapse above the text.

Why it is built this way

• All navigation is HTML written by build_site.py, so it works with scripts off, and check_site_links.mjs already verifies every link and fragment it adds. site/site.js adds conveniences only. site/theme.js applies a remembered theme before first paint.
• render_docs.mjs now returns each doc's headings and per-section text. Phase 6 (search) reads the section text.
• The renderer emits the heading links itself, not through raw HTML, so the allowlist is untouched.
• Table alignment becomes a class instead of an inline style, ahead of the CSP in phase 7.
• The explainer gets the shared header through a <!-- site:header --> slot. The build refuses if the slot is missing, and checks that before deleting anything.
• Form borders and histogram bars now meet 3:1 contrast in both themes, which is part of Calculator accessibility: contrast, error association, and live regions #53.

Checked

• ruff, mypy --strict, and pytest pass (483 tests). The 10 new tests in tests/test_build_site.py cover the header, sidebar, contents list, and previous/next.
• render_docs.mjs --self-test passes 20 cases. check_floor_parity.mjs and check_site_links.mjs pass on the built site (11 pages).
• In a real browser (Playwright, 1440, 1100 and 375 px, light and dark):
  • anchors land below the sticky header, and the highlight follows scrolling, including the last section;
  • the theme survives a reload;
  • a page with JavaScript disabled still has its sidebar, contents list, and previous/next links, and the script-only buttons stay hidden;
  • no horizontal overflow at 375 px.

Next: phase 6 (search), then phase 7 (the explainer's opening block, CSP, and #25, #53, #55, #57).

🤖 Generated with Claude Code