UseJDL Docs

Appearance

Architecture ​

This site is designed to stay simple: VitePress builds static files, Cloudflare Pages serves them, and Cloudflare Access or Workers protect the internal section when needed.

Core Responsibilities ​

VitePress ​

VitePress is the documentation layer.

  • Markdown files in docs/ are the source of truth
  • docs/.vitepress/config.ts defines navigation and sidebar structure
  • pnpm docs:build generates a static site

VitePress should stay focused on content structure and rendering. It is not responsible for authentication.

Cloudflare Pages ​

Cloudflare Pages is the hosting layer.

  • It runs the build command
  • It publishes the generated static files
  • It serves the same site globally without needing a custom application server

For this repository, Pages should publish docs/.vitepress/dist.

Cloudflare Access ​

Cloudflare Access is the recommended first step for protecting internal docs.

  • Protect the /internal/ path with an access policy
  • Keep the public site open
  • Avoid adding application code just to enforce simple team-only access

This is the lightest way to introduce authentication for internal readers.

Cloudflare Workers ​

Workers are optional and should be added only if path-based Access is not enough.

Use Workers when you need:

  • Custom request logic
  • More advanced routing rules
  • Integration with other edge-side checks

Workers extend the delivery layer, but they should not replace VitePress as the content source.

Public And Internal Boundary ​

Keep the split clear:

  • docs/public/ contains material safe for external readers
  • docs/internal/ contains maintainer and team-only material

Do not duplicate the same page in both areas. If some content must be public, write a shorter public version and keep the detailed operational notes in internal.

  1. Build the site with VitePress.
  2. Deploy the static output to Cloudflare Pages.
  3. Publish the whole site.
  4. Add Cloudflare Access to /internal/*.
  5. Add a Worker later only if access control or routing needs become more specific.

This keeps deployment simple while leaving room for stricter controls later.