Contributing & Regenerating the Docs
This site lives in website/ at the repo root — separate from the internal docs/ design pack. It is a VitePress guide plus a TypeDoc-generated API reference, deployed to GitHub Pages.
Local development
bash
pnpm install
# generate the API reference, then run the dev server
pnpm --filter @terminaldz/zrexpress-docs docs:dev
# full production build (typedoc → vitepress build)
pnpm --filter @terminaldz/zrexpress-docs docs:build
# preview the built site
pnpm --filter @terminaldz/zrexpress-docs docs:preview
# check internal links and verify code snippets compile against the SDK
pnpm --filter @terminaldz/zrexpress-docs docs:checkHow it fits together
- Guide pages are hand-written Markdown under
website/— sourced from the SDK code anddocs/API_REFERENCE.md. Every code sample uses a request shape that is proven to return2xxagainst the live API (see API Quirks and the Playground). - The API Reference (
/api/) is generated by TypeDoc (typedoc-plugin-markdown+typedoc-vitepress-theme) from the SDK's three entry points (src/index.ts,src/webhooks/index.ts,src/nestjs/index.ts) and their TSDoc. It is regenerated on every build — never editwebsite/api/by hand (it's gitignored). The build treats any TypeDoc warning as an error. docs:checkfails on a broken internal link or a snippet that doesn't compile, so a bad reference can't ship.
Rules
- Don't hand-edit generated output (
website/api/). - Don't document a method or field that doesn't exist in
src/— if the SDK surface changes, the API Reference regenerates and the checks catch stale prose. - Keep examples honest: prefer shapes extracted from the compiled examples (
examples/node-basic,examples/nest-app,examples/webhook-listener) and the verified Playground journey.
Deployment
Pushing to main (touching website/**, src/**, docs/**, README.md, CHANGELOG.md, or examples/**) runs .github/workflows/docs.yml, which builds the site and deploys it to GitHub Pages at https://terminaldz.github.io/zrexpress-sdk/. Enabling Pages (Settings → Pages → Source: GitHub Actions) is a one-time manual step.