Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The documentation site

The docs you are reading are published as an mdBook site on Cloudflare Pages, deployed by hand from a checkout. The book has two halves:

  • Prose — the hand-written docs/*.md in this repo, plus the root README.md as the landing page.
  • API reference — generated from the package sources by TypeDoc at build time, never committed.

One-time setup

mdBook is a Rust binary, so pnpm install does not bring it in. Install it once:

cargo install mdbook          # or: brew install mdbook
mdbook --version              # 0.5 or newer

TypeDoc is a dev dependency, so nothing else is needed.

Working on the docs

pnpm docs:dev     # stage + build + serve on http://localhost:3000, opens a browser
pnpm docs:build   # stage + build into .docs-build/book

scripts/docs.ts stages everything into .docs-build/src and then runs mdBook over it (book.toml points src there). .docs-build/ is generated and gitignored — never edit anything under it; your changes are wiped on the next build. Because the sources are staged copies, pnpm docs:dev does not hot-reload edits to docs/*.md: re-run it.

Adding a page

  1. Write docs/your-page.md.
  2. Add it to docs/SUMMARY.md — that file is the book’s table of contents and the sidebar order. A page that is not in SUMMARY.md is not in the book.
  3. Add a row to the table in docs/README.md, which stays the index for people reading on GitHub.

Two entries in SUMMARY.md deliberately do not resolve when browsing docs/ on GitHub: index.md (the root README, staged under that name) and everything under api/ (generated). They resolve in the built book.

The API reference needs no maintenance — it follows the src/index.ts of every package under packages/. TypeDoc names modules after their path, so scripts/docs.ts retitles each page with the package name from its package.json.

Deployment

The docs are not deployed by CI (the only workflow is the release one, cd.yml); deploy from your machine (needs wrangler 4.x and wrangler login, or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID in the environment; Pages project sms-docs):

pnpm docs:build
wrangler pages deploy .docs-build/book --project-name=sms-docs --branch=main                          # production
wrangler pages deploy .docs-build/book --project-name=sms-docs --branch="$(git branch --show-current)" # preview

The publish-docs skill (.claude/skills/publish-docs) walks through the same steps plus the one-time Pages project setup and Cloudflare Access restrictions.

The docs build is deliberately not part of pnpm check: it needs a binary that is not in the lockfile, and a broken sidebar should not block a release.