Skip to content

Previewing the docs site locally

Runs docs/ as a live site at http://127.0.0.1:8000 before anything is pushed. Edit a markdown file, save, and the browser refreshes on its own.

Every time

cd C:\Users\zeler\Projects\octopodia-abos
mkdocs serve

Open http://127.0.0.1:8000. Stop it with Ctrl+C.

That's it. The two commands below are only for the first run, or if something breaks.

First time on a machine

cd C:\Users\zeler\Projects\octopodia-abos
pip install -r docs/requirements.txt

Needs Python 3.12+. Check with python --version.

Before pushing

mkdocs build --strict

--strict turns warnings into errors, so a dead internal link or a nav entry pointing at a missing file fails here rather than shipping a 404. Cloudflare Pages runs the same build — if it fails locally, it fails there.

Delete the generated site/ folder afterwards if you like; it's gitignored and rebuilt every time.

When it doesn't work

mkdocs : The term 'mkdocs' is not recognized Not installed, or not on PATH. Run the first-time install above. If it still fails, use python -m mkdocs serve instead — same thing, bypasses PATH entirely.

Config file 'mkdocs.yml' does not exist Wrong directory. mkdocs.yml sits in the repo root, not in docs/. Run cd C:\Users\zeler\Projects\octopodia-abos first.

[Errno 10048] address already in use An earlier mkdocs serve is still running — check other terminal windows. Or use a different port: mkdocs serve -a 127.0.0.1:8001.

Build fails on a link you didn't touch Expected while the ADR cross-references are still settling. The error names the file and the broken target. Fix the link rather than dropping --strict.

Page exists but isn't in the sidebar The nav: block in mkdocs.yml is explicit. An unlisted page still builds and is searchable — it just has no menu entry. Add it to nav: if it should appear.

Notes

  • Local preview reads straight from docs/. Nothing is published and nothing leaves your machine.
  • mkdocs serve picks up edits to markdown automatically. Changes to mkdocs.yml need a restart — Ctrl+C, run it again.
  • Only the repo root and docs/ matter here. This has nothing to do with the VPS (ADR-0029) — the docs site is deliberately independent of it.