Docs Site Deployment

The engineering documentation site is a static VitePress build served from Cloudflare Pages at docs.eccdps.org. This page covers how that site is built, published, and operated.

Pipeline

push to main (docs/**)
        ↓
GitHub Actions (deploy.yml)
        ↓
npm ci → npm run build
        ↓
wrangler pages deploy (Cloudflare Pages, project "docs")
        ↓
docs.eccdps.org (production branch: main)

The pipeline is defined in .github/workflows/deploy.yml in the docs repository. It runs only when content or pipeline files change (paths filter) and can also be triggered manually from the Actions tab (workflow_dispatch).

Repository layout

The docs site lives in its own repository:

• docs/ — VitePress content; the build output is docs/.vitepress/dist
• wrangler.toml — Cloudflare Pages project name (docs) and build output directory
• .github/workflows/deploy.yml — the deployment pipeline
• package.json — npm run build (site build) and npm run deploy (manual Pages upload)

The production branch is main. Pushes to other branches create preview deployments, never production.

One-time setup

These steps are performed once, when the pipeline is first stood up.

1. Push the repository to GitHub

The workflow runs on GitHub, so the docs repository must exist there. The "Edit this page" link in the site footer assumes github.com/eccdps/docs — adjust editLink in docs/.vitepress/config.mts if the repository lands elsewhere.

2. Create a Cloudflare API token

In the Cloudflare dashboard: My Profile → API Tokens → Create Token. Use the "Edit Cloudflare Workers" template or a custom token with the Account → Cloudflare Pages: Edit permission scoped to the account.

Add two repository secrets (Settings → Secrets and variables → Actions):

Secret	Value
CLOUDFLARE_API_TOKEN	The API token created above
CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID (dashboard sidebar / Workers overview)

No other credentials are required: the site build reads no environment variables and the Pages upload is authenticated by the token alone.

3. Create the Pages project (optional)

The first pipeline run auto-creates the docs project if it does not exist. To create it explicitly with the correct production branch:

npx wrangler pages project create docs --production-branch=main

4. Attach the custom domain

In the Cloudflare dashboard: Workers & Pages → docs → Custom domains → Set up a custom domain → docs.eccdps.org.

Because eccdps.org is on Cloudflare DNS, adding the custom domain automatically creates the CNAME docs → docs.pages.dev record. If the zone were hosted elsewhere, the equivalent record would be:

CNAME  docs  →  docs.pages.dev

Deploying

• Automatic: push to main touching docs/** (or the pipeline files) builds and deploys to production.
• Manual re-run: Actions tab → "Deploy docs" → Run workflow.
• Preview deployments: pushes to non-main branches and pull requests receive preview URLs under docs.pages.dev; these never touch production.

Verification

After a deploy:

1. The workflow run finishes green.
2. curl -sI https://docs.eccdps.org/ returns 200 OK.
3. The page title and sidebar render (the accessibility tree or browser devtools will show the full navigation).
4. Local search returns results for a known identifier such as rpc_report_action.
5. The dark/light theme toggle works.

Manual deploy (no CI)

Useful for the first publish or when GitHub is unavailable. Authenticate with npx wrangler login once, then:

npm run build
npm run deploy

Rollback

The Cloudflare Pages dashboard keeps every deployment: Workers & Pages → docs → Deployments → ⋯ → Rollback to this deployment. Production traffic switches immediately; the previous build is retained, so a bad release can be reverted without rebuilding.

Operational notes

• The site is fully static — there is no server process, no database, and no environment configuration at runtime. A deploy either works or the previous version stays live.
• docs/.vitepress/dist/ and node_modules/ are gitignored; the build is always produced by CI (or by npm run build for manual deploys).
• If the pipeline fails, check the workflow logs first (build error vs. authentication error). Authentication failures mean the token or account ID secret changed or expired — see the Cloudflare dashboard, then update the repository secrets.