notes

Built with MkDocs and the Material for MkDocs theme.

Setup

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

requirements.txt pins the mkdocs-material version, which pulls in MkDocs itself.

Commands

• .venv/bin/mkdocs serve: local preview at http://127.0.0.1:8000 that reloads on save
• .venv/bin/mkdocs build --strict: builds the site into site/ and fails on warnings such as broken links

Layout

• mkdocs.yml: site settings, theme and Markdown extensions
• docs/: the pages, one Markdown file per page; with no nav in mkdocs.yml, every page appears in the menu automatically (subfolders become sections)
• docs/CNAME: custom domain, copied into the built site

Deploy

.github/workflows/deploy.yml runs mkdocs build --strict on every push to main and publishes site/ to GitHub Pages.

Docs

• MkDocs: https://www.mkdocs.org/user-guide/
• Material for MkDocs: https://squidfunk.github.io/mkdocs-material/reference/

Appearance

The site uses the Etch design system: docs/stylesheets/etch.css holds Etch's colour, type, spacing and stroke tokens and maps Material's variables onto them (Dark = Material's slate scheme, Light = default). The Geist and Geist Mono fonts are in docs/fonts/ under the SIL Open Font License (docs/fonts/OFL.txt); font: false in mkdocs.yml stops Material loading Google Fonts.