Deploying

A build is plain static files, so deployment is pointing a host at the repo. This page covers the host settings, a CI recipe, and the two pass-through files most sites eventually want.

Static hosts

Every static host wants the same two answers: a build command and an output directory. For Cairn they are always cairn build and dist. Let the host build from source on each push rather than committing dist/; the build is fast enough that there is nothing to cache around.

Host settings
Setting	Value	Notes
`build command`	cairn build	No flags. Configuration belongs in `cairn.toml`, not the host dashboard.
`output directory`	dist	Or whatever `output` is set to in `[build]`.
`install step`	none	The binary has no dependencies; fetch it and run it.

Building in CI

Where you drive deployment from your own pipeline, the job is three steps: fetch the binary, build, upload dist/. The recipe below is generic YAML; translate the upload step to whatever your host or CDN expects.

.ci/deploy.yml

deploy-docs:
  on: push to main
  steps:
    - run: curl -fsSL https://get.cairn.build | sh
    - run: cairn check       # fail the job on broken links
    - run: cairn build
    - upload: dist/        # your host's deploy step

Warning

Never set drafts = true in a deployed build. Draft pages are unfinished by definition, and a config edit made for a local preview will publish every one of them on the next push. Keep drafts local: cairn serve always shows them without any config change.

Redirects and headers

Cairn does not process redirects or headers itself; they are host concerns. It does guarantee the files reach the host: anything in static/ is copied into the build root untouched, which is exactly where hosts look for their _redirects and _headers conventions.

static/_redirects

# old paths from the previous docs site
/docs/install   /guides/install/   301
/docs/*         /                  302

With hash_assets on (the default), fingerprinted CSS and theme assets are safe to serve with far-future cache headers; HTML should stay at a short max-age so page updates land immediately.