api-docs/ is published to https://api-docs.casola.ai by
.github/workflows/publish-api-docs.yml, which copies
this directory to the root of the gh-pages branch on every push to main that touches it.
GitHub Pages’ own Jekyll build renders the markdown — there is no generator to install and no build
output to review, so what a reviewer reads in a PR diff is exactly what ships.
This is deliberately separate from apps/docs (Starlight → docs.casola.ai), which is a Worker
with an OpenAPI build step and a deploy lane tied to the platform release. These pages are prose
about an API contract; they should be publishable without a platform deploy.
Both steps need repository-admin and DNS access, so they are operator actions, not CI ones.
1. Enable Pages. Repository → Settings → Pages → Build and deployment:
| Setting | Value |
|---|---|
| Source | Deploy from a branch |
| Branch | gh-pages |
| Folder | / (root) |
| Custom domain | api-docs.casola.ai |
| Enforce HTTPS | on (available a few minutes after the DNS record resolves) |
The gh-pages branch does not exist until the workflow runs once — run it from the Actions tab
(Publish API docs → Run workflow) before configuring the branch source.
2. Add the DNS record in Cloudflare, zone casola.ai:
CNAME api-docs casola-ai.github.io DNS only (grey cloud)
The grey cloud matters: proxying through Cloudflare in front of GitHub Pages breaks Pages’
certificate issuance for the custom domain. CNAME in the published output carries the domain, so
Pages keeps the custom domain across force-pushes.
curl -sI https://api-docs.casola.ai | head -3
curl -sS https://api-docs.casola.ai/04-prompt-overrides.html | grep -o '<title>.*</title>'
Links between pages are written as ./04-prompt-overrides.md so they work when reading the folder
on github.com; jekyll-relative-links (declared in _config.yml) rewrites them to
.html in the published site. Keep writing them as .md.
Edit the markdown, open a PR, merge. The workflow publishes within a minute of the merge; Pages
serves the new build shortly after. workflow_dispatch re-publishes without a content change.
Keep the docs true to the code: every field, cap and error code in these pages is one the API
actually enforces, and the value of that is entirely in it staying so. When you change a mint
parameter, a cap, or an error code in services/api, update the matching table here in the same
PR.