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 exampledocs.example.org. A base path such asexample.org/docs/is not supported. - Trailing slashes. Page URLs end with
/and map to<path>/index.html. The host must serveindex.htmlfor a folder URL. - Not found page.
dist/404.htmlis 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:
- uses: actions/checkout@v4
with:
fetch-depth: 0Cloudflare Workers static assets
A Worker with only static assets serves dist/ without any Worker code. Put a wrangler.jsonc next to site.json:
{
"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.directoryis the build output.not_found_handling: "404-page"returns404.htmlwith status 404 for missing paths.- The default
html_handling,auto-trailing-slash, servesguides/quickstart/index.htmlat/guides/quickstart/, which matches docsp URLs. routeswithcustom_domain: trueattaches the Worker to a hostname of a zone in your Cloudflare account. Leave it out to use theworkers.devaddress.
Build, then deploy:
$ npx docsp build
$ npx wrangler deployDeploy 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.
- run: npm ci
- run: npx docsp build
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: deployThe 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. |
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.