@forge-clients/docs

@forge-clients Documentation Site

The documentation site for the @forge-clients monorepo, built with Astro Starlight.

Live site: robertmassaioli.github.io/forge-clients

Building the docs

Commands are run from this docs/ directory:

Command	Action
npm install	Install dependencies
npm run dev	Start local dev server at localhost:4321
npm run build	Build production site to ./dist/
npm run preview	Preview the production build locally

Note: From the monorepo root you can also run pnpm --filter @forge-clients/docs run dev etc.

How TypeDoc auto-generation works

The API reference under src/content/docs/reference/ is automatically generated by starlight-typedoc from the TSDoc comments in packages/core/src/. It runs automatically as part of every npm run dev and npm run build — you never need to run TypeDoc manually.

The entry point is packages/core/src/index.ts. Only @forge-clients/core is included in the reference docs; the Jira and Confluence packages expose 1500+ generated functions that are not practical to document individually.

What to track in git

Path	Track in git?	Reason
src/content/docs/reference/	✅ Yes	Generated output is checked in so diffs are visible in PRs and the site can be built without running TypeDoc first (useful on CI if TypeDoc fails). Regenerated automatically on every build.
src/content/docs/**/*.md (non-reference)	✅ Yes	Hand-written content — always track.
dist/	❌ No	Build output — excluded by .gitignore.
.astro/	❌ No	Astro type-gen cache — excluded by .gitignore.
node_modules/	❌ No	Dependencies — excluded by .gitignore.

Keeping reference docs up to date

Because the reference pages are checked in, they must be regenerated whenever TSDoc comments in packages/core/src/ change. The workflow is:

• Edit source TSDoc comments in packages/core/src/
• Run npm run build (or npm run dev) inside docs/ — TypeDoc regenerates src/content/docs/reference/ automatically
• Commit both the source changes and the updated reference pages together

The CI workflow (.github/workflows/ci.yml) runs the docs build on every push, so stale reference pages will cause a build failure if the TypeDoc output diverges from what is checked in.

Site structure

docs/
├── src/
│   ├── content/
│   │   └── docs/
│   │       ├── getting-started/   # Quick start, concepts, installation
│   │       ├── guides/            # Auth, error handling, pagination, adapters
│   │       ├── jira/              # Jira-specific how-to guides
│   │       ├── confluence/        # Confluence-specific how-to guides
│   │       ├── generator/         # Generator CLI guide
│   │       └── reference/         # ⚡ Auto-generated by TypeDoc — do not edit by hand
│   └── styles/
│       └── custom.css
├── astro.config.mjs               # Starlight + TypeDoc plugin configuration
├── package.json
└── tsconfig.json

Do not edit files in src/content/docs/reference/ by hand. They are overwritten on every build. Add or improve TSDoc comments in packages/core/src/ instead.