Skip to content
ReviewPhin Docs

Contributing to docs

Documentation source lives in docs/. Generated container output lives in public/ and should not be edited by hand.

Preview locally

Section titled “Preview locally”
Terminal window
pnpm docs:dev

Build for the container image

Section titled “Build for the container image”
Terminal window
pnpm docs:build:container

The container build does not include the homepage by default. Build the homepage only for the public static site, such as the GitHub Pages release workflow, by setting:

Terminal window
REVIEWPHIN_BUILD_HOMEPAGE=true pnpm docs:build

PostHog analytics are also disabled by default. To build a tracked static site, set REVIEWPHIN_POSTHOG_KEY at build time. REVIEWPHIN_POSTHOG_HOST is optional and defaults to https://us.i.posthog.com.

How the container serves docs

Section titled “How the container serves docs”

The docs site is authored in docs/ and built into the runtime static directory. The container docs build writes:

  • public/docs/ for Starlight documentation pages and assets,
  • public/pagefind/ for the Starlight local search bundle.

Existing runtime assets under public/github/setup/ and public/favicon.png are preserved. The Fastify app serves public/ at /, then registers setup and webhook routes.

Because docs pages live under /docs/*, they must not shadow /healthz, /setup/*, /webhooks/*, or /github/setup/*. The container docs build also removes public/index.html so the runtime root can be owned by the application, not the static docs site. Route smoke checks should verify those paths after each docs integration change.

Writing rules

Section titled “Writing rules”

Use the reviewphin-docs skill before changing docs or official-site copy.

  • Keep GitLab first in navigation and examples, while giving GitHub and custom providers equal structure where supported.
  • Keep SQLite first in storage docs, then Flotiq, then custom adapters.
  • Write for operators and maintainers in plain, task-oriented language.
  • Do not duplicate guidance across pages; link to the canonical page instead.

Fact checks

Section titled “Fact checks”

Verify commands, routes, environment variables, and provider behavior against source before publishing. Use schema-verification-skill for storage contract, schema, migration, or adapter documentation.