Skip to content

Runbook — MkDocs Resident (seanyo-docs)

Purpose

Provide a rendered, read-only documentation view at:

https://docs.seanyo.ca

MkDocs is used strictly as a presentation layer. The canonical source of truth remains CLI-first Markdown under:

/opt/sys/docs-md

Resident Identity

  • Resident name: mkdocs / seanyo-docs
  • Type: static site generator (presentation only)
  • Exposure: public IP, non-indexed, TLS via Caddy

Canonical Locations

Resident runtime:

/opt/sys/residents/mkdocs/seanyo-docs/

Python virtual environment:

/opt/sys/residents/mkdocs/seanyo-docs/.venv/

MkDocs configuration:

/opt/sys/residents/mkdocs/seanyo-docs/mkdocs.yml

Source documentation (canonical):

/opt/sys/docs-md/

MkDocs-rendered docs directory:

/opt/sys/docs-md/seanyo-docs/mkdocs/docs/

Build output (generated):

/opt/sys/residents/mkdocs/seanyo-docs/site/

Web root served by Caddy:

/var/www/sam-docs/

Configuration Notes

MkDocs is explicitly pointed at the canonical docs tree.

Key configuration (excerpt):

docs_dir: /opt/sys/docs-md/seanyo-docs/mkdocs/docs
site_dir: /opt/sys/residents/mkdocs/seanyo-docs/site

This ensures: - Docs are authored once (CLI-first) - MkDocs never becomes the canonical source - Rebuilds are deterministic

Build and Deploy (Canonical Procedure)

Activate the resident virtual environment:

source /opt/sys/residents/mkdocs/seanyo-docs/.venv/bin/activate

Build the site:

cd /opt/sys/residents/mkdocs/seanyo-docs
mkdocs build -f mkdocs.yml --clean

Deploy to the Caddy web root:

sudo rsync -a --delete site/ /var/www/sam-docs/

Verification

Confirm HTTPS response:

curl -I https://docs.seanyo.ca | sed -n '1,20p'

Local TLS + routing verification (bypass DNS):

curl -vkI --resolve docs.seanyo.ca:443:127.0.0.1 https://docs.seanyo.ca

Expected: - HTTP/2 200 - Valid Let's Encrypt certificate - server: Caddy

Common Failure Modes

mkdocs: command not found

Cause: - Virtual environment not activated.

Fix:

source /opt/sys/residents/mkdocs/seanyo-docs/.venv/bin/activate
command -v mkdocs
mkdocs --version

rsync: Permission denied

Cause: - /var/www/sam-docs is owned by www-data.

Fix: - Use sudo for rsync (intentional). - Do not change ownership permanently.

Site builds but content is stale

Cause: - Docs edited outside canonical path. - Wrong docs_dir.

Fix: - Verify source files exist under:

    /opt/sys/docs-md/
  • Rebuild with --clean.

Operational Principles

  • CLI Markdown is canonical.
  • MkDocs is disposable and reproducible.
  • No stub documents.
  • No documentation lives only in MkDocs.
  • Residents are documented via runbooks, not inferred.
  • playbooks/static-site-with-caddy.md
  • playbooks/python-venv-resident.md
  • playbooks/rsync-deploy-pattern.md