Contributing to the Docs

Where content lives

Content	Location	Notes
Cross-package guides	apps/docs/src/guide/	Authored directly in the docs app
Package-specific docs	packages/{name}/docs/	Synced into the site by generate
API reference	packages/{name}/src/ JSDoc	Generated by TypeDoc
Homepage	apps/docs/src/index.md	VitePress home layout

Editing guides

Edit Markdown files directly under apps/docs/src/guide/. Run the dev server to preview:

npm run docs:dev

Then open http://localhost:5173/rule-io-sdk/ (or DOCS_BASE=/ npm run docs:dev for http://localhost:5173/).

Editing package docs

Edit files under packages/{name}/docs/. The sync script copies them into the site during generate:

npm run docs:generate   # syncs package docs + regenerates API reference
npm run docs:dev        # start dev server with fresh content

Link rules

Links within a package's docs/ directory may use relative paths. Links to other parts of the site must use VitePress root-relative paths (starting with /):

<!-- Correct: root-relative link to API reference -->
See the [API Reference](/api/client/src/) for full details.

<!-- Correct: relative link within the same package's docs -->
See [Sending Emails](./sending-emails).

<!-- Wrong: escaping link — the sync script will reject this -->
See [README](../../README.md).

The sync script fails loudly if any Markdown link escapes the docs/ directory of its package.

Editing API reference (JSDoc)

The API reference is generated from JSDoc comments in the source files. Edit the JSDoc in packages/{name}/src/ and regenerate:

npm run docs:generate

Guidelines for JSDoc comments on public symbols:

• A one-sentence description summarising what the symbol does.
• @param descriptions for non-obvious parameters.
• @returns description when the return type is non-obvious.
• @example blocks for primary usage patterns (3–10 lines).
• @throws for expected error cases (e.g. RuleApiError).
• @since for tracking when a symbol was introduced.
• @deprecated with migration guidance for deprecated symbols.
• @internal on any symbol that should not appear in the public docs.

Do not describe TypeScript type signatures in prose — TypeDoc renders them automatically. Do not describe implementation details.

Building the static site

npm run docs:generate   # generate API docs + sync package docs
npm run docs:build      # build the full static site
npm run docs:preview    # preview the built site locally

Cleaning generated output

npm run docs:clean

Removes apps/docs/src/api/, apps/docs/src/packages/, apps/docs/.vitepress/dist/, and apps/docs/.vitepress/cache/. Run this before generate if you need a clean slate.