UseJDL Docs

Appearance

Deployment Checklist ​

Use this page when you are ready to connect the repository to Cloudflare Pages and protect the internal section.

1. Repository Readiness ​

Before deployment, confirm:

  • pnpm install completes successfully
  • pnpm docs:build completes successfully
  • docs/.vitepress/config.ts matches the actual pages in docs/public/ and docs/internal/
  • no sensitive information was added to docs/public/

2. Cloudflare Pages Setup ​

Create a Pages project connected to this repository and use these settings:

  • Framework preset: None
  • Build command: pnpm docs:build
  • Build output directory: docs/.vitepress/dist
  • Node.js version: 20 or newer

After the first deploy, verify:

  • / renders the homepage
  • /public/ is reachable without authentication
  • /internal/ renders before access control is enabled

3. Cloudflare Access Setup ​

Use Access as the default protection mechanism for internal docs.

Recommended flow:

  1. Create an Access application for the Pages domain.
  2. Add a policy that protects /internal/*.
  3. Keep / and /public/* open.
  4. Test with an allowed identity.
  5. Test with an identity that should be denied.

This gives you path-based protection without adding application code to the docs site.

4. When To Add A Worker ​

Add a Worker only if Access is not enough.

Typical reasons:

  • you need custom routing before serving the docs
  • you need more detailed request logic than a simple path policy
  • you want to enforce extra checks at the edge

If you add a Worker later, keep the responsibility narrow: routing and access logic only.

5. Release Checks ​

Before each release:

  • build locally with pnpm docs:build
  • preview locally with pnpm docs:preview
  • review new pages for correct public vs internal placement
  • verify internal links still point to the right pages
  • confirm README still matches the real commands and deployment flow

6. Codex Maintenance Routine ​

For ongoing maintenance with Codex:

  • ask Codex to read related pages before editing
  • keep changes focused on one topic or one section at a time
  • ask Codex to update sidebar links when adding or removing a page
  • run a build after every documentation change set

This keeps the repository stable and makes review straightforward.