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

1. Edit source TSDoc comments in packages/core/src/
2. Run npm run build (or npm run dev) inside docs/ — TypeDoc regenerates src/content/docs/reference/ automatically
3. 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.