Cloudflare Docs Deployment¶
The documentation is a static MkDocs site. It is deployed to Cloudflare Pages through Direct Upload so documentation traffic remains separate from the AWS application host. Verify current Cloudflare plan limits before relying on a particular pricing tier.
This project uses Direct Upload because GitHub Actions already owns dependency installation and the strict MkDocs build. Cloudflare Pages projects cannot switch between Git integration and Direct Upload after creation, so create this project in Direct Upload mode. A separate project would be required to change modes later.
Deployment Flow¶
When documentation is pushed to main, GitHub Actions runs the strict MkDocs build and uploads the generated site/ directory to Cloudflare Pages with Wrangler. Other branches can create preview deployments without changing the public documentation site.
Cloudflare Setup¶
Create a Cloudflare Pages Direct Upload project named:
packytrace-docs
Authenticate Wrangler and create the Direct Upload project explicitly:
npx wrangler pages project create packytrace-docs
Future deployments upload the GitHub Actions-built site/ directory. See Cloudflare's official Direct Upload guide and continuous-integration guide.
Create a Cloudflare API token with:
Account > Cloudflare Pages > Edit
Add these GitHub Actions secrets:
| Secret | Value |
|---|---|
| CLOUDFLARE_ACCOUNT_ID | Cloudflare account ID |
| CLOUDFLARE_API_TOKEN | Cloudflare token with Pages edit access |
Optional GitHub Actions variables:
| Variable | Value |
|---|---|
| CLOUDFLARE_PAGES_PROJECT | Defaults to packytrace-docs |
| DOCS_SITE_URL | Example: https://packytrace-docs.pages.dev |
GitHub Workflow¶
The workflow is .github/workflows/deploy-docs-cloudflare.yml.
It:
- checks out the repository;
- sets up Python;
- verifies Cloudflare secrets exist;
- runs make docs-build;
- uploads site/ with Wrangler direct upload.
The GitHub deployment environment is named:
packytrace-docs
Deploys from main should publish to:
https://packytrace-docs.pages.dev
Deploys from other branches may produce preview URLs such as:
https://<hash>.packytrace-docs.pages.dev
That is normal.
Local Check¶
Before pushing docs changes:
make docs-build
This runs MkDocs in strict mode before Cloudflare receives the site. Review informational link and navigation messages as well as the exit status; the current link plugin does not promote every missing anchor to a build failure.