Skip to content

Documentation Theming

Documentation Theming Guardrails

This note captures the current, “good” state of the MkDocs theming so we can intentionally return to it if future edits drift.

Default Typography (Always On)

  • Fonts load exclusively from Google Fonts via docs/stylesheets/extra.css.
  • Body text uses Lato; headings, nav labels, and footers use Montserrat with the weights defined in that CSS file.
  • Do not add additional font imports unless they replace Lato/Montserrat across the whole site.

Optional ABS Layout

  • All layout/presentation overrides (two-column nav, hidden tabs, card styles, language flags, etc.) are gated behind the abs-layout class on <body>.
  • The overrides live in docs/stylesheets/extra.css and only apply when JavaScript (or a template) intentionally adds document.body.classList.add('abs-layout').
  • If the layout ever looks “plain,” verify whether that class is being applied before editing CSS.

Restore / Verify Procedure

  1. Inspect docs/stylesheets/extra.css to ensure the top section still defines fonts globally and later rules remain wrapped in body.abs-layout.
  2. Run python scripts/krr.py (Kill, Rebuild, Restart) to clear caches, rebuild the site, and serve it locally at http://127.0.0.1:8000.
  3. Check the served site with and without abs-layout applied to confirm both states work.

Keeping this note updated whenever theming changes gives us a single source of truth for what “correct” looks like.