Skip to content

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:check

How it fits together ​

  • Guide pages are hand-written Markdown under website/ — sourced from the SDK code and docs/API_REFERENCE.md. Every code sample uses a request shape that is proven to return 2xx against 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 edit website/api/ by hand (it's gitignored). The build treats any TypeDoc warning as an error.
  • docs:check fails 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.

Released under the MIT License. Not affiliated with ZR Express.