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
Runner [self-hosted, Linux, X64, homelab-ci] — WSL pool; see github-self-hosted-runners.md
Python actions/setup-python@v6, Python 3.13
Node tooling actions/setup-node@v5, Node 22, npm ci for markdownlint
Action runtime FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true while the repo completes the Node 24 transition
Deploy action cloudflare/wrangler-action@v4
Pages project hldocs-c0acdec9
Trigger Push to main when docs/**, mkdocs.yml, or .github/workflows/docs.yml 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).

The Pages site is intentionally public as of 2026-06-26. Do not publish plaintext secrets, private host keys, private IP credentials, or unredacted incident artifacts. Contractor assessments and review reports may be published under docs/reviews/ when they contain links/evidence but no sensitive material.

Local preview

From repo root:

uv sync
npm ci
uv run mkdocs serve          # http://127.0.0.1:8000
uv run mkdocs build --strict # same check as CI — must pass before merge
uv run python scripts/lint-markdown.py

Markdown is linted in CI via npm ci + scripts/lint-markdown.py. Use uv run python scripts/lint-markdown.py --fix before committing docs changes.

Publish pipeline

  1. Merge PR to main (or push directly).
  2. Deploy Docs workflow runs:
  3. actions/checkout@v5
  4. actions/setup-python@v6 with Python 3.13
  5. actions/setup-node@v5 with Node 22
  6. npm ci
  7. python scripts/lint-markdown.py
  8. pip install mkdocs-material
  9. mkdocs build --strict
  10. Ensure Pages project exists: npx --yes wrangler@3 pages project list
  11. Create it if missing: npx --yes wrangler@3 pages project create hldocs-c0acdec9 --production-branch main
  12. Deploy with cloudflare/wrangler-action@v4: pages deploy site/ --project-name=hldocs-c0acdec9 --commit-dirty=true
  13. Confirm green run: Actions → Deploy Docs.
  14. 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.

The workflow intentionally separates Node concepts:

  • setup-node installs Node 22 for repo-local npm tooling (markdownlint-cli2 currently requires Node >=22).
  • FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true exercises GitHub JavaScript actions on Node 24 during the platform transition.
  • Project bootstrap still calls npx --yes wrangler@3; deployment itself uses cloudflare/wrangler-action@v4.

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. For review packages, add them under the Reviews nav section and keep a top-level README with executive summary, findings, and appendix links.

Optional hardening

Task Status Notes
Pages deploy via GitHub Actions ✅ Done Secrets in repo settings
Cloudflare Access on docs URL ❌ Declined Owner accepted public Pages site (2026-06-26)

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/spadoople/homelab/blob/main/...
  • Fix stale #anchor links after heading renames.
  • Reproduce locally: uv run mkdocs build --strict.

Node or Wrangler errors

  • Confirm the job is using actions/setup-node@v5 with Node 22; that controls npm tooling, not the JavaScript action runtime.
  • Keep FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true unless the Node 24 transition has been retired across all workflows.
  • If project creation fails, inspect the npx --yes wrangler@3 pages project ... step separately from the final cloudflare/wrangler-action@v4 deploy step.

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.