Skip to content
docsp
On this page

Deployment

Publish dist/ on any static host, with a Cloudflare Workers static assets example.

docsp build writes a static site to dist/. Any host that serves files works, with three conditions:

  • Root of a domain. The site must be served at / of its host, for example docs.example.org. A base path such as example.org/docs/ is not supported.
  • Trailing slashes. Page URLs end with / and map to <path>/index.html. The host must serve index.html for a folder URL.
  • Not found page. dist/404.html is the not found page. Configure the host to return it for missing paths.

Set url in site.json to the public address, for example https://docs.example.org. docsp uses it for the canonical link of every page.

Full git history in CI

The "updated" date of a page comes from its frontmatter, or else from the date of the last git commit of the file. A shallow clone gives every page the date of the last commit. With GitHub Actions, check out the full history:

YAML
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

Cloudflare Workers static assets

A Worker with only static assets serves dist/ without any Worker code. Put a wrangler.jsonc next to site.json:

JSONwrangler.jsonc
{
  "name": "acme-docs",
  "compatibility_date": "2026-11-01",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  },
  "routes": [{ "pattern": "docs.example.org", "custom_domain": true }]
}
  • assets.directory is the build output.
  • not_found_handling: "404-page" returns 404.html with status 404 for missing paths.
  • The default html_handling, auto-trailing-slash, serves guides/quickstart/index.html at /guides/quickstart/, which matches docsp URLs.
  • routes with custom_domain: true attaches the Worker to a hostname of a zone in your Cloudflare account. Leave it out to use the workers.dev address.

Build, then deploy:

Terminal
$ npx docsp build
$ npx wrangler deploy

Deploy from GitHub Actions

cloudflare/wrangler-action installs wrangler and runs the deploy, so wrangler does not need to be a dependency of the site. It needs an API token with permission to edit Workers, and the account id, stored as repository secrets.

YAML.github/workflows/docs.yml
- run: npm ci
- run: npx docsp build
- uses: cloudflare/wrangler-action@v3
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    command: deploy

The docsp repository deploys this site the same way; see .github/workflows/docs.yml and site/wrangler.jsonc.

Other hosts

Host Setting to check
Any static web server Serve index.html for folder URLs and 404.html for missing paths.
GitHub Pages Use a custom domain or a <user>.github.io repository: project pages live under a base path, which docsp does not support.
Netlify, Vercel, S3 behind a CDN Publish dist/. Set the not found page to 404.html.
Note:

Local preview. Any static file server previews dist/. In the docsp repository: node scripts/serve.mjs site/dist 4400, then open http://localhost:4400/. That server answers missing paths with a plain text 404, not 404.html.

↑ ↓ to move↵ to openSearching docsp