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 is 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 or later. 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 is gitignored and rebuilt every time.

& "C:\Users\zeler\anaconda3\Scripts\mkdocs.exe" build --strict

When it does not 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 did not 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 is not 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, then run it again.
  • Only the repo root and docs/ matter here. This has nothing to do with the VPS (ADR-0029), because the docs site is deliberately independent of it.