Docs Site and Wrangler Deploy

docs/ is a VitePress documentation site inside the root pnpm workspace. It also includes Cloudflare Wrangler configuration so the generated static site can be deployed to Cloudflare Pages.

Structure

docs/
  .vitepress/config.ts
  public/
    _headers
    logo.svg
  zh/
    index.md
    ...
  package.json
  wrangler.toml
  *.md
  reference/

English pages live at the docs root and are the default locale. Simplified Chinese pages live under docs/zh/ and are served from /zh/.

Local Development

Install all workspace dependencies from the repository root:

pnpm install

Start the docs dev server:

pnpm docs:dev

Build:

pnpm docs:build

Preview the release build:

pnpm docs:preview

Wrangler Configuration

docs/wrangler.toml:

"$schema" = "./node_modules/wrangler/config-schema.json"

name = "home-harbor"
pages_build_output_dir = ".vitepress/dist"
compatibility_date = "2026-07-01"

name is the Cloudflare Pages project name. pages_build_output_dir points to the VitePress static output directory. Do not add an [assets] section here; Wrangler reserves that for Workers static assets and rejects it during Pages deploy validation. Treat this file as the source of truth for the Pages project; if settings are changed in the Cloudflare dashboard, sync them back into wrangler.toml.

Direct Upload Deploy

Build first:

pnpm docs:build

Deploy:

pnpm docs:deploy

The deploy script runs wrangler pages deploy .vitepress/dist --project-name home-harbor in the homeharbor-docs package. homeharbor-docs is the pnpm package name, and home-harbor is the Cloudflare Pages project name.

Direct Upload CI needs these environment variables:

• CLOUDFLARE_API_TOKEN: account API token with Account > Cloudflare Pages > Edit permission for the account that owns home-harbor.
• CLOUDFLARE_ACCOUNT_ID: Cloudflare account ID, especially when the token can access multiple accounts or CI should not rely on account auto-detection.

If Wrangler reports Authentication error [code: 10000] after the VitePress build completes, the static build succeeded. Rotate or adjust CLOUDFLARE_API_TOKEN, then deploy again.

For first-time setup or login:

pnpm --filter homeharbor-docs exec wrangler login
pnpm --filter homeharbor-docs exec wrangler pages project create home-harbor

Cloudflare Pages Git Integration

If using Git integration, set the project root directory to:

docs

Build command:

pnpm install && pnpm build

Output directory:

.vitepress/dist

Deploy command:

leave blank

Do not set the Pages Git integration deploy command to pnpm deploy. Pages publishes the output directory itself; pnpm docs:deploy is only for local or external CI direct upload.

Use Node 20 or newer.

Headers

docs/public/_headers is copied verbatim into the output directory. It gives hashed assets long-lived caching and adds basic security headers to all pages.

Do not enable HTML auto-minification that rewrites comments. VitePress/Vue hydration can depend on output structure, and HTML auto-minify can cause mismatches.

Updating Docs

1. Edit Markdown or VitePress configuration.
2. Run pnpm docs:build.
3. Use pnpm docs:preview when visual inspection is useful.
4. Commit source files, not docs/.vitepress/dist.
5. Publish via Git integration or pnpm docs:deploy.