Cloudflare Docs Deployment

The documentation is a static MkDocs site. It is deployed to Cloudflare Pages because Cloudflare's free plan is enough for static docs and keeps documentation traffic away from the AWS application host.

Do not use Cloudflare's Git-connected build for this repository. Cloudflare sees the root package.json and may run its own npm ci, which is unrelated to the docs build. GitHub Actions owns the build.

Flow

sequenceDiagram participant Maintainer participant GitHub participant Actions participant Cloudflare Maintainer->>GitHub: push docs change to main GitHub->>Actions: run Deploy Docs to Cloudflare Pages Actions->>Actions: make docs-build Actions->>Cloudflare: wrangler pages deploy site/ Cloudflare-->>Maintainer: Pages URL

Cloudflare Setup

Create a Cloudflare Pages Direct Upload project named:

packytrace-docs

The first project creation may require uploading the current site/ folder manually. That upload only creates the project. Future deploys come from GitHub Actions.

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:

  1. checks out the repository;
  2. sets up Python;
  3. verifies Cloudflare secrets exist;
  4. runs make docs-build;
  5. 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 and catches broken links before Cloudflare receives the site.