Skip to content

Deploying the docs site (Cloudflare Pages)

The docs site (this site) is built with Zensical and hosted on Cloudflare Pages. Static HTML, free tier, instant cache invalidation.

Local preview

cd docs-site
uvx zensical serve

Opens a hot-reloading dev server at http://localhost:8000/. Save any markdown file → page reloads. Change zensical.toml → restart.

Local build

cd docs-site
uvx zensical build

Produces a static site under docs-site/site/. Open docs-site/site/index.html in your browser to verify.

First-time Cloudflare Pages setup

Done once per project; you can skip this section if the project already has a Pages site.

  1. Sign in to the Cloudflare dashboard.
  2. Workers & Pages → Create application → Pages → Connect to Git.
  3. Pick the GitHub repo (you'll authorise the Cloudflare GitHub app the first time).
  4. Configure build:
  5. Production branch: main
  6. Build command: pip install zensical && cd docs-site && zensical build
  7. Build output directory: docs-site/site
  8. Root directory (advanced): leave as the repo root.
  9. Environment variables (if needed):
  10. PYTHON_VERSION = 3.12 (Cloudflare's default Python is older; pin if you hit issues).
  11. Save and Deploy.

The first build runs immediately. Subsequent deploys happen automatically on every push to main. Preview deploys happen on every PR — Cloudflare leaves a comment on the PR with the preview URL.

Custom domain

If you've configured docs.lifefile.app:

  1. Pages site → Custom domains → Set up a custom domain.
  2. Enter docs.lifefile.app.
  3. Cloudflare adds the CNAME for you (because the domain is on Cloudflare DNS already). If it isn't, follow the on-screen DNS instructions.

Workflow

The convenient cycle:

  1. Edit a markdown file in docs-site/docs/.
  2. uvx zensical serve to preview.
  3. Commit + push to a feature branch.
  4. Open a PR → Cloudflare leaves a preview-deploy comment within ~30 seconds.
  5. Merge → production updates within ~30 seconds.

When the build breaks

  • 404 on a nav link — usually a typo in zensical.toml's nav table. Compare against the directory tree.
  • pymdownx.something not found — the pip install zensical step is incomplete; pin the Zensical version in the build command if you hit version drift.
  • Missing image / asset — paths in markdown are relative to the markdown file's location. Move or fix the path.

Reverting

Cloudflare keeps every deploy. Pages site → Deployments → Rollback restores any previous build with one click.