# 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`:

```json title="wrangler.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 title=".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`.
:::
