Skip to content

Docs site

This site is MkDocs with the Material theme. Sources are Markdown under docs/, configured by mkdocs.yml at the repo root.

Run it locally

pip install -r requirements-docs.txt
mkdocs serve

Then open http://127.0.0.1:8000/. The server watches docs/ and mkdocs.yml and reloads on save.

If mkdocs is not on PATH after installing, use python -m mkdocs serve.

Build like CI does

mkdocs build --strict

--strict turns warnings into errors, which is what the workflow runs. The usual cause of a strict failure is a link to a page that does not exist, or a page not listed in nav. Fix the link or add the page — do not drop --strict.

Output goes to site/, which is gitignored.

Adding a page

  1. Create the Markdown file under the right folder: docs/design/, docs/systems/ or docs/dev/.
  2. Add it to nav in mkdocs.yml. A page not in nav builds but is unreachable, and strict mode complains.
  3. Link to it from wherever it is relevant. Links are relative file paths including the .md — ../systems/hose-system.md, not /systems/hose-system/. MkDocs rewrites them.

Writing conventions

  • Systems pages document code that exists. If the code and the page disagree, the page is wrong. Update the page in the same PR as the code.
  • Design pages may describe things that do not exist, but must be marked. Use an admonition at the top:
!!! note "Draft"
    Nothing on this page is implemented.
  • Admonition types in use: note for drafts, warning for things that are wired wrong or partially wired, danger for whole systems that do not run, bug for specific defects, tip for practical advice, info for context.
  • Mermaid diagrams go in a fenced ```mermaid block. They are rendered by pymdownx.superfences with Material's built-in Mermaid support — no extra plugin, no CDN config.
  • Keep prose tight. Say the number, name the file, skip the throat-clearing.

Deployment

These docs ship as part of the public site, underneath the landing page. deploy-site.yml runs on every push to main that touches docs/**, web/**, mkdocs.yml, requirements-docs.txt or the build scripts, and can also be run by hand (workflow_dispatch).

The job installs mkdocs-material, runs tools/build-site.sh — which copies web/ into web-dist/ and then runs mkdocs build --strict -d web-dist/docs — and deploys web-dist/ to Cloudflare Pages with wrangler.

Live at https://hoseboy.com/docs/. That URL is not linked from the landing page: the docs are for people who were given the address.

Warning

A strict-mode failure fails the deploy and the site keeps serving the previous version. Run mkdocs build --strict before pushing docs changes.

Pinning

requirements-docs.txt currently floats mkdocs-material>=9.5 and the workflow installs mkdocs-material unpinned, which is fine while the site is small. If a theme release ever breaks the build, pin an exact version in both places at once.