Deploying to Cloudflare (MkDocs)¶

This guide covers a repeatable workflow for deploying this MkDocs site to Cloudflare and troubleshooting common failures.

Prerequisites¶

A GitHub repository with this project
A Cloudflare account with Workers enabled
A working local build:

make build

If local build fails, fix that first before trying cloud deployment.

1) Verify local project structure¶

For this setup, your repository should include:

mkdocs.yml
requirements.txt
docs/ (source content)
site/ (generated output from MkDocs build)

site/ is generated by mkdocs build and is what gets deployed as static assets.

2) Connect Git repository in Cloudflare¶

In Cloudflare Worker build settings:

Connect the correct GitHub repository.
Select the production branch (for this repo: master).
Confirm the repository name carefully. A wrong repo connection causes missing-file errors during build.

3) Configure build and deploy commands¶

Use the following commands:

Build command:

pip install -r requirements.txt && mkdocs build --strict

Deploy command:

npx wrangler deploy --assets site --compatibility-date 2026-03-23 --name hyperpastadev-website

Non-production/version command:

npx wrangler versions upload --assets site --compatibility-date 2026-03-23 --name hyperpastadev-website

4) Configure root path and branch control¶

Root directory/path: /
Production branch: master (for this repository).

If branch naming changes in GitHub later, update Cloudflare production branch to match.

5) Trigger deployment¶

After connecting or reconfiguring:

Push a commit to the production branch.
Open Cloudflare build history.
Confirm:
dependency install succeeds
mkdocs build --strict succeeds
wrangler deploy --assets site ... succeeds

6) Validate deployed site¶

Check:

Worker URL (*.workers.dev) loads the full MkDocs site
CSS, JS, and images load correctly
key internal pages and links work

If you see only Hello world, Cloudflare is serving a default Worker response instead of static assets.

7) Add custom domain and DNS¶

In Worker settings:

Go to Domains & Routes
Add route(s), for example:
hyper-pasta.dev/*
www.hyper-pasta.dev/*
In DNS, add proxied CNAME records:
@ -> hyperpastadev-website.inkpenguin2010.workers.dev
www -> hyperpastadev-website.inkpenguin2010.workers.dev
Wait a few minutes, then verify both:
https://hyper-pasta.dev
https://www.hyper-pasta.dev

Both DNS records and both Worker routes are required for apex and www to work reliably.

8) Multi-domain mapping for this site¶

This site is configured to be reachable from multiple domains:

www.hyper-pasta.dev
www.rebooted.dev

To support this setup in Cloudflare:

Add DNS records for each hostname pointing to the Worker hostname:
www on hyper-pasta.dev -> hyperpastadev-website.inkpenguin2010.workers.dev (proxied)
www on rebooted.dev -> hyperpastadev-website.inkpenguin2010.workers.dev (proxied)
Add Worker routes for each hostname:
www.hyper-pasta.dev/*
www.rebooted.dev/*
Validate both URLs load the same deployed site content.

Troubleshooting¶

Error: `Could not open requirements file: requirements.txt`¶

Likely causes:

wrong Git repository connected
wrong branch selected
incorrect build root/path

Actions:

Confirm Cloudflare is connected to the intended repository.
Confirm production branch matches your actual branch.
Re-run build.

Error: `A compatibility_date is required when publishing`¶

Fix:

add --compatibility-date YYYY-MM-DD to deploy/version commands, or
define it in wrangler.toml.

Warning about Worker name mismatch¶