Skip to content

How to Deploy MkDocs to Cloudflare Pages

When to use this

Setting up or updating the eco|monetize documentation platform. There are two deployment targets:

Site Project name URL Auth
Internal ops docs (Phase 1) eco-docs-internal docs.ecomonetize.com Cloudflare Access — invite only
Public ERI docs (Phase 2) eco-docs-public help.ecomonetize.com Public

This playbook covers both. Phase 1 is the current active build.

Prerequisites

  • Cloudflare account access (info@ecomonetize.com at dash.cloudflare.com)
  • ecomonetize.com on Cloudflare nameservers — this is a hard blocker. Both subdomains route through Cloudflare DNS. Without nameserver migration from GoDaddy, no subdomain routing works.
  • GitHub repo access (eco-monetize/claude — or the relevant docs repo)
  • Admin access to GitHub repo settings (to add secrets)

One-time setup (do once per Pages project)

Step 1 — Create the Cloudflare Pages project

  1. Go to dash.cloudflare.com → Workers & Pages → Create → Pages
  2. Choose Connect to Git → authorize GitHub → select the eco-monetize/claude repo
  3. Set build configuration:
  4. Project name: eco-docs-internal (or eco-docs-public for Phase 2)
  5. Production branch: main
  6. Build command: (leave blank — GitHub Actions handles the build)
  7. Build output directory: site
  8. Click Save and Deploy — the first deploy will likely fail because we're managing builds via GitHub Actions, not Cloudflare's built-in CI. That's expected.

Alternative: Create the project without Git connection using the Wrangler CLI: 

npx wrangler pages project create eco-docs-internal

Step 2 — Get your Cloudflare API token

  1. dash.cloudflare.com → My Profile → API Tokens → Create Token
  2. Use the Edit Cloudflare Workers template, then add:
  3. Cloudflare Pages — Edit permission
  4. Scope to your account
  5. Copy the token — you only see it once. Store in 1Password as CLOUDFLARE_API_TOKEN (eco-docs-internal).

Step 3 — Get your Account ID

  1. dash.cloudflare.com → right sidebar on any zone page → Account ID
  2. Or: npx wrangler whoami (if Wrangler is installed)

Step 4 — Add GitHub secrets

In the GitHub repo: Settings → Secrets and variables → Actions → New repository secret

Secret name Value
CLOUDFLARE_API_TOKEN Token from Step 2
CLOUDFLARE_ACCOUNT_ID Account ID from Step 3

Step 5 — Update the GitHub Actions workflow

Replace the deploy job in .github/workflows/docs.yml. See the current file at /Claude/.github/workflows/docs.yml. The key change: remove GitHub Pages deploy steps, add Wrangler Pages deploy.

The updated deploy section: 

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy site --project-name=eco-docs-internal --commit-dirty=true

Also remove from the workflow: - permissions: pages: write and id-token: write (not needed for Cloudflare) - environment: name: github-pages block - actions/upload-pages-artifact step - actions/deploy-pages step

Step 6 — Update mkdocs.yml site_url

Change site_url from the GitHub Pages URL to the Cloudflare domain: 

site_url: https://docs.ecomonetize.com

Step 7 — Configure Cloudflare Access (Phase 1 only)

  1. dash.cloudflare.com → Zero Trust → Access → Applications → Add an application
  2. Choose Self-hosted
  3. Application name: eco|monetize Internal Docs
  4. Session duration: 24 hours (adjust to taste)
  5. Application domain: docs.ecomonetize.com
  6. Create an Allow policy:
  7. Policy name: Team + Approved External
  8. Action: Allow
  9. Include rule: Emails → add each authorized email address (team members, investors, contractors)

Adding a new user: Zero Trust → Access → Applications → eco|monetize Internal Docs → Edit policy → add their email. No VPN, no Tailscale — they get an email-based one-time code login.

Ongoing deploy process (automatic after setup)

Every push to main that touches a docs-relevant path triggers the GitHub Actions workflow: 1. Assembles the docs/ directory from knowledge/, system/sops/, and session archive 2. Builds the MkDocs static site into site/ 3. Deploys site/ to Cloudflare Pages via Wrangler

No manual steps required after the one-time setup.

Verification

After a deploy: - [ ] GitHub Actions run completes green — check the repo's Actions tab - [ ] Cloudflare Pages dashboard shows the new deployment under Workers & Pages → eco-docs-internal - [ ] docs.ecomonetize.com resolves (requires nameserver migration to be complete) - [ ] Cloudflare Access gate appears on first visit — login with email one-time code - [ ] Site content loads correctly — spot-check the Tools and Playbooks sections

Troubleshooting

Problem Fix
Error: No project found Wrangler can't find the Pages project. Confirm --project-name matches exactly what's in the Cloudflare dashboard.
Authentication error CLOUDFLARE_API_TOKEN secret is wrong or expired. Regenerate in Cloudflare dashboard, update GitHub secret.
Subdomain doesn't resolve ecomonetize.com is still on GoDaddy nameservers. Rick must migrate to Cloudflare before subdomains work.
Access gate not appearing Cloudflare Access policy isn't applied to the domain. Check Zero Trust → Access → Applications.
Build succeeds but deploy fails Check that site/ directory exists after mkdocs build. If MkDocs errors, look at the build step logs.
commit-dirty=true warning Expected — the workflow assembles docs into the docs/ directory at build time, creating uncommitted changes. The flag allows this.

Phase 2 differences (help.ecomonetize.com)

  • Separate Cloudflare Pages project: eco-docs-public
  • Separate GitHub Actions workflow file (different trigger paths — only content changes)
  • No Cloudflare Access policy — public site
  • site_url: https://help.ecomonetize.com in the Phase 2 mkdocs config
  • Requires CMO (Michelle) to author initial content before first deploy
  • [[cloudflare]] — platform reference (/Claude/knowledge/platforms/cloudflare.md)
  • [[github]] — repo and Actions reference
  • /Claude/sessions/documentation.engineering/docs-platform-build-plan.md — full phase plan
  • /Claude/.github/workflows/docs.yml — the workflow file this playbook updates

Last verified

2026-04-22 — documentation.engineering. Architecture confirmed by CEO (Rick) + COO (Morgan) 2026-04-22. Nameserver migration (GoDaddy → Cloudflare) still pending — Rick's action item before first live deploy.