Skip to content

Cloudflare Pages (homelab docs)

How homelab documentation is built and published to Cloudflare Pages.

Live site: hldocs-c0acdec9.pages.dev

Overview

Item Value
Source docs/ + mkdocs.yml in homelab repo
Build mkdocs-material, mkdocs build --strict
CI .github/workflows/docs.yml
Pages project hldocs-c0acdec9
Trigger Push to main when docs/**, mkdocs.yml, or workflow file changes
Secrets GitHub CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID

Docs CI is separate from Traefik’s Cloudflare DNS token (services/traefik/.env.sops.yaml). Use a Pages-scoped API token for GitHub Actions; keep Traefik DNS-01 on its own token (see Public edge DR).

Local preview

From repo root (Python 3.13+):

pip install mkdocs-material
mkdocs serve          # http://127.0.0.1:8000
mkdocs build --strict # same check as CI — must pass before merge

Markdown is also linted in CI via npm ci + scripts/lint-markdown.py.

Publish pipeline

  1. Merge PR to main (or push directly).
  2. Deploy Docs workflow runs:
  3. lint-markdown.py
  4. mkdocs build --strict
  5. Ensure Pages project exists (wrangler pages project list)
  6. wrangler pages deploy site/ --project-name=hldocs-c0acdec9
  7. Confirm green run: Actions → Deploy Docs.
  8. Spot-check the live site (journal index, new runbook pages).

--strict fails on warnings (broken links to files outside docs/, bad anchors). Link to repo files with GitHub blob URLs, not ../../scripts/... paths.

Adding pages to navigation

Edit mkdocs.yml nav: — orphan pages under docs/ build but are easy to miss. After adding a runbook, include it under Runbooks and in runbooks/index.md.

Optional hardening

Task Status Notes
Pages deploy via GitHub Actions ✅ Done Secrets in repo settings
Cloudflare Access on docs URL ⏸ Deferred Email OTP or IP allowlist — CF Access docs

Troubleshooting

Deploy Docs failed on mkdocs build --strict

  • Read the log for WARNING lines (strict treats them as errors).
  • Common fixes:
  • Replace ../../services/... / ../../scripts/... links with https://github.com/notarealemail/homelab/blob/main/...
  • Fix stale #anchor links after heading renames.
  • Reproduce locally: mkdocs build --strict.

Pages project missing

Workflow auto-creates hldocs-c0acdec9 if absent. If create fails, check token has Account → Cloudflare Pages → Edit.

Site stale after green deploy

Hard-refresh or check deployment in Cloudflare dashboard → Workers & Pages → hldocs-c0acdec9 → Deployments.