Docs Deployment#

Copy as MarkdownView Markdown

The documentation lives at https://ox-content.dev. Cloudflare Workers Builds builds and deploys it to Workers Static Assets using the cf CLI on pushes to main. GitHub Actions validates the deployment with an unauthenticated dry-run and does not publish the site.

The deployment includes the docs at /, Rust API documentation at /api/, and the playground at /playground/. tools/deploy/cloudflare.config.ts declares the ox-content-docs Worker and its ox-content.dev Custom Domain.

Local Deployment#

Install workspace dependencies and authenticate once:

vp install
vp run deploy#cf -- auth login
vp run deploy#cf -- auth whoami

Build and deploy from the repository root:

vp run deploy#docs

The task builds Rust, local npm packages (including Code Play), docs, the playground, and Rust API documentation with vp run build. It assembles their output into dist/, then uses Cloudflare's @cloudflare/build-output-utils to write native Build Output under tools/deploy/.cloudflare/output/v0/. It runs cf deploy --prebuilt --mode production against that output. The cf package is pinned to 1.0.0-beta.9 in the deployment workspace. Deployment scripts are TypeScript executed directly by Node 26's stable type stripping, with explicit .ts imports and no loader or transpilation step.

Extra arguments are forwarded to cf deploy. Validate the full build without publishing or needing Cloudflare credentials:

vp run deploy#docs -- --dry-run

To prepare the same Build Output without running a deployment command:

vp run deploy#docs:build

Run cf directly through the same pinned CLI after preparing the build:

vp run deploy#cf -- deploy --prebuilt --mode production --dry-run
vp run deploy#cf -- deploy --prebuilt --mode production

The CLI wrapper runs in tools/deploy. Always use --prebuilt --mode production when deploying the prepared output. Use vp run dev:docs to preview the docs locally. See Cloudflare prebuilt deployments.

Workers Builds Setup#

In the Cloudflare dashboard, create or select the ox-content-docs Worker and connect ubugeeei-prod/ox-content through its Git integration. Install the Cloudflare Workers and Pages GitHub App for the organization with access to this repository.

Use these build settings:

Set these build variables, which are ordinary version and installation settings rather than secrets:

The build script installs the repository's Rust toolchain, the frozen pnpm dependencies, and the browsers needed to render documentation. It runs vp run deploy#docs:build to assemble the same Build Output validated in CI. The separate deploy command uses the pinned cf CLI without rebuilding.

Workers Builds automatically generates and stores its deployment credential inside Cloudflare. No CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID GitHub Actions secrets need to be created, copied, or rotated by repository maintainers. This is Cloudflare Git integration, not GitHub Actions OIDC authentication. See Workers Builds configuration and build image settings.

The .github/workflows/deploy.yml workflow builds and runs cf deploy --prebuilt --mode production --dry-run without credentials on deployment-related pull requests, pushes to main, and manual runs. Production publishing happens only in Workers Builds after a push to its production branch or a manual retry in Cloudflare. Enable automatic builds once these commands are available on main, and check the first successful production build and the public URLs before considering the hosting migration complete.

Custom Domain#

The ox-content.dev zone must be active in the same Cloudflare account used by cf. The config sets worker.domains: ["ox-content.dev"], so cf configures the domain and Cloudflare manages DNS and HTTPS certificates. No separate origin server is needed. See Cloudflare Custom Domains.

An existing CNAME for the same hostname prevents Custom Domain creation. Check for conflicting records before the first deployment. A successful dry-run validates the bundle and config; the first authenticated deployment verifies account access and domain registration.

URLs and Asset Paths#

Docs builds default to OX_CONTENT_DOCS_BASE=/ and OX_CONTENT_DOCS_SITE_URL=https://ox-content.dev. The playground production base defaults to /playground/. Generated metadata, sitemaps, feeds, OG images, and client assets therefore use the custom domain and root-relative paths.

OX_CONTENT_DOCS_BASE, OX_CONTENT_DOCS_SITE_URL, and OX_CONTENT_PLAYGROUND_BASE remain available for alternate build targets. For another deployment target, update the Worker name and domains in tools/deploy/cloudflare.config.ts, then rebuild before deploying.

Cloudflare serves directory indexes and extensionless HTML routes with auto-trailing-slash handling. Missing pages use the generated 404.html with an HTTP 404 status.