UseJDL Docs

Appearance

Cloudflare Rollout ​

This page documents the recommended rollout order for this repository:

  1. Deploy the VitePress site to Cloudflare Pages.
  2. Verify public and internal routes on the Pages domain.
  3. Protect /internal/* with Cloudflare Access.
  4. Add a Worker later only if Access is not enough.

This keeps the initial deployment simple and reduces the chance of mixing content problems with access-control problems.

1. Deploy To Cloudflare Pages First ​

Use Cloudflare Pages as the hosting target for the static VitePress output.

Recommended Pages settings:

  • Framework preset: None
  • Production branch: main
  • Build command: pnpm docs:build
  • Build output directory: docs/.vitepress/dist
  • Root directory: repository root
  • Node.js version: 20 or newer

Deployment flow:

  1. Push the repository to GitHub.
  2. In the Cloudflare dashboard, open Workers & Pages.
  3. Create a new Pages project from the Git repository.
  4. Enter the build settings above.
  5. Trigger the first production deploy.

After the first deploy, verify the generated *.pages.dev domain:

  • / loads the homepage
  • /public/ is reachable
  • /internal/ is reachable before Access is enabled
  • page navigation and clean URLs work as expected

2. Keep The First Deploy Static ​

Do not add a Worker during the first rollout unless there is a real routing or request-processing requirement.

For this repository:

  • VitePress already generates the full static site
  • Pages already serves the static output globally
  • Access can protect the internal path without adding application code

This is the simplest production shape and the easiest one to debug.

3. Protect /internal/* With Cloudflare Access ​

After Pages is live, create an Access application for the Pages hostname and protect the internal path.

Recommended approach:

  1. Open Cloudflare Zero Trust.
  2. Go to Access controls -> Applications.
  3. Create a self-hosted application for the Pages hostname.
  4. Set the protected path to /internal/*.
  5. Add an Allow policy for the team identities that should read internal docs.
  6. Leave / and /public/* outside that protected path.

Notes:

  • Cloudflare Access supports protecting specific application paths, not only whole hostnames.
  • More specific application paths take precedence over broader ones.
  • Avoid an Allow policy that effectively grants access to everyone.

4. Optional Hardening After Access Works ​

Once the path-level Access rule is confirmed, you can decide whether to turn on the account-level setting Require Cloudflare Access Protection.

Use this only after reviewing the impact carefully.

Why:

  • it changes the account behavior to deny hostnames without an Access application
  • public hostnames need an explicit Access application with an allow or bypass path strategy if required
  • a careless rollout can block traffic unexpectedly

For this docs project, this setting is optional hardening, not part of the first deployment.

5. When To Add A Worker ​

Add a Worker only if the site needs logic that Pages plus Access does not cover.

Typical reasons:

  • custom edge routing
  • request transformation
  • route-specific logic before serving assets
  • future API endpoints or custom auth flows

If a Worker is added later, keep the responsibility narrow. It should not replace VitePress or duplicate Access unless there is a clear need.

6. Release Checklist ​

Before each rollout:

  • run pnpm install
  • run pnpm docs:build
  • verify all new pages are in the correct public or internal directory
  • verify navigation links match the actual pages
  • verify no sensitive material leaked into public

After deployment:

  • verify the *.pages.dev domain
  • verify /internal/* requires login after Access is enabled
  • verify /public/* remains publicly reachable
  • verify denied users cannot open internal pages