Skip to content

Deploy docs to Cloudflare Pages

  • Last verified: 2026-04-27
  • Estimated time: 10 minutes (one-time setup)
  • Risk: Low — read-only static site

When to use this

First-time setup of the public docs site at https://docs-961tech.pages.dev (or a custom domain). After setup, deploys are automatic on every push to master.

Why Cloudflare Pages

  • Free for unlimited bandwidth and projects
  • Free for private GitHub repos (GitHub Pages requires Pro for private repos; CF Pages doesn't)
  • Native preview deploys per PR
  • Optional Cloudflare Access for password-gating the site without code changes

Prerequisites

Steps

1. Connect GitHub to Cloudflare Pages

In Cloudflare Dashboard:

  1. Workers & Pages → Create application → Pages → Connect to Git
  2. Authorise the Cloudflare GitHub app — grant access to Amine32/961tech only (don't grant org-wide access for a personal account)
  3. Pick the repo Amine32/961tech

2. Configure the build

Setting Value
Project name 961tech-docs
Production branch master
Framework preset None
Build command bash scripts/build-docs.sh
Build output directory site

Why a script and not an inline command? First attempt used pip install ... && mkdocs build directly. The CF Pages UI mangled a backslash into the command and mkdocs build\ failed with "No such command". Wrapping in scripts/build-docs.sh removes that whole class of issue. | Root directory | (leave blank — repo root) | | Environment variables | PYTHON_VERSION = 3.12 |

Click Save and deploy.

3. Wait for first build

CF Pages builds the site (takes ~2-3 min for first build, faster after via cache). On success you get a URL like https://961tech-docs.pages.dev.

Verify by opening the URL — the docs index page should render with the Material theme, dark/light toggle, and search.

4. (Optional) Custom subdomain

If you have a domain in Cloudflare DNS:

  1. Pages project → Custom domains → Set up custom domain
  2. Enter docs.961tech.com (or whatever subdomain)
  3. CF auto-creates the CNAME — no manual DNS edit needed

5. (Optional) Password-gate with Cloudflare Access

If the docs contain sensitive info you don't want public:

  1. Zero Trust → Access → Applications → Add an application → Self-hosted
  2. Application name: 961tech docs
  3. Domain: the Pages URL (or custom domain)
  4. Add a policy: "Email is aminov.02@hotmail.com" (or any verified email)
  5. Save — first visit prompts for email, sends a one-time code, then access is granted

Free Zero Trust plan covers up to 50 users — plenty for solo + occasional client/contractor access.

Verification

  • Push a commit that touches docs/ → check that CF Pages triggers a build → the change appears on the live site
  • Open a PR that touches docs/ → confirm a preview URL is generated in the PR check status
  • The GitHub Action docs.yml also runs on the same paths and should pass for any PR before merge

Rollback

If a deploy renders broken content:

  1. Pages dashboard → Deployments → find the last good deploy
  2. Promote to Production on that deploy
  3. Then fix the source and re-push

CF keeps deployment history indefinitely on the free tier.

Troubleshooting

Symptom Likely cause Fix
Build fails with pymdownx.highlight error pygments and pymdown-extensions version mismatch Pinned in docs/requirements.txt — make sure CF picks up that file. Verify build command references docs/requirements.txt.
Diagrams don't render mermaid CDN blocked or wrong version mkdocs.yml pins mermaid version. If still broken, check browser console for the actual error
404 on a section index nav in mkdocs.yml references a missing file mkdocs build --strict locally would have caught this — make sure CI is gating PRs
Slow build First build always slow due to no cache Subsequent builds are 30-60s thanks to pip and CF build cache