Skip to content

Hosting the docs on Cloudflare

The documentation site is built with MkDocs Material and deployed to Cloudflare as a Worker serving static assets (Workers Builds + wrangler deploy). Cloudflare clones this repo, builds it, and serves dist/.

Why a Worker and not Pages? Cloudflare's current "connect a Git repo" flow creates a Worker, not a Pages project. That's fine — a Worker with an [assets] block and no script serves a static site directly. The only thing that was missing originally was the wrangler.toml telling wrangler deploy to serve dist/; without it, wrangler deploy ships a default Worker that returns Hello World!.

One-time Cloudflare dashboard setup

In your Worker → Settings → Build:

Setting Value
Build command bash build-docs.sh
Deploy command npx wrangler deploy
Root directory / (repo root)

The static-asset wiring lives in wrangler.toml ([assets] directory = "./dist"), and the Python version (3.12) is pinned by .python-version. After saving, trigger Deployments → Retry / Create deployment.

What the build does

build-docs.sh is the single build entrypoint (local and Cloudflare):

  1. Installs mkdocs + mkdocs-material from requirements-docs.txt if not present.
  2. Mirrors gtm/ into docs/gtm/ (MkDocs only serves files under docs/).
  3. Runs mkdocs build --clean, emitting the static site to dist/.

wrangler deploy then uploads dist/ as the Worker's static assets.

Local preview

bash build-docs.sh serve   # live-reload at http://127.0.0.1:8000
bash build-docs.sh         # one-off build into dist/

Prefer a real Pages project instead?

If you'd rather use Cloudflare Pages (explicit "Build output directory" field, no wrangler.toml): delete this Worker, then Workers & Pages → Create → Pages tab → Connect to Git, and set Build command bash build-docs.sh + Build output directory dist. Be sure to pick the Pages tab — the default flow creates a Worker.