Skip to content

Design

The styling source of truth is the root DESIGN.md. Keep it in sync with theme.css.

Current Presentation Contract

The Material site is intentionally configured for a wide knowledge-base layout:

  • full-width desktop grid;
  • integrated sidebar table of contents;
  • aligned header search and active page-title rails;
  • hidden duplicate sidebar title;
  • square Markdown bullets;
  • rendered source-ID cleanup;
  • auto-linked known page titles in article body text, excluding table headers, with same-page references rendered as non-clickable subtly tinted text;
  • article link colour and self-reference/link highlights scoped to .md-content .md-typeset, excluding Material button links and chrome links so controls and footer credits keep their Material foreground styling;
  • protected product-name phrase wrapping for narrow cells and navigation labels.

Build-time presentation behavior lives in hooks/presentation_rules.py. Browser-side phrase wrapping fallback lives in phrase-wrap.js. Layout styling lives in theme.css.

Change Process

Before changing theme, CSS, logo assets, navigation, admonitions, tables, or revision UI styling:

  1. Read DESIGN.md.
  2. Update DESIGN.md and theme.css together when the contract changes.
  3. Add or update presentation tests in tests/test_presentation_rules.py for source cleanup, auto-linking, and phrase wrapping behavior.
  4. Add or update CSS selector regression tests in tests/test_theme_css.py when changing link, footer, or Material chrome styling.
  5. Run npm run verify.