Cloudflare Pages Docs Runbook
This runbook configures the Docusaurus docs site for docs.mayadev.cloud.
Project
| Setting | Value |
|---|---|
| Cloudflare Pages project | maya-docs |
| Production domain | docs.mayadev.cloud |
| Repository root directory | / |
| Build command | pnpm docs:build |
| Build output directory | apps/docs/build |
| Production branch | main |
| Framework preset | None or Docusaurus |
| Build system version | v3 |
NODE_VERSION | 24.9.0 |
PNPM_VERSION | 10.18.3 |
Use the repository root as the Pages root so pnpm can resolve the monorepo workspace and lockfile.
Keep NODE_VERSION aligned with .node-version and PNPM_VERSION aligned with the root packageManager.
Local Preflight
Run from the workspace root:
pnpm install --frozen-lockfile
pnpm verify:docs-site
pnpm verify:docs-site runs the source boundary verifier, TypeScript check, and Docusaurus static build.
Custom Domain
Attach docs.mayadev.cloud to the maya-docs Pages project in Cloudflare. DNS ownership stays in Cloudflare; do not commit DNS tokens or account secrets to the repo.
The DNS record must be:
docs.mayadev.cloud CNAME maya-docs.pages.dev
Do not use an A record for the docs host. Cloudflare Pages custom-domain verification reports CNAME record not set until the host points at the Pages project domain.
Preview Deployments
Enable preview deployments for non-production branches if the Cloudflare project is connected through Git. Preview deployments must use the same build command and output directory as production.
Cache And Headers
apps/docs/static/_headers is copied into the Docusaurus static output and sets security headers for the static site. Cloudflare may additionally cache hashed assets aggressively. HTML rollback is handled by Pages deployment rollback, not by manual cache editing.
Rollback
Rollback through Cloudflare Pages:
- Open the
maya-docsPages project. - Select the last known good production deployment.
- Use Cloudflare Pages rollback/promote controls.
- Run the smoke checks in
.docs/ops/smoke-checks.md. - Record the incident and follow-up issue in Linear.
Direct Upload
v0 does not document a direct-upload command. Git-connected Cloudflare Pages deployment is the supported path.
Current direct-upload command:
wrangler pages deploy apps/docs/build --project-name=maya-docs --branch=main
If direct upload remains a supported release path, add a pinned wrangler dependency or a pinned CI action in the same change as the release automation. Do not use unpinned pnpm dlx wrangler in release documentation.