# Repository layout

Where the docsp code, the example site, this documentation site and the tests live, and how to work on them.

The docsp repository is a pnpm workspace. You need Node.js 22.12 or later and pnpm 11.

| Path | Content |
|---|---|
| `packages/docsp` | The package `@fabricators/docsp`: CLI, Astro integration, components, layouts, tokens, schemas, unit tests. |
| `examples/site` | Example portal with three projects, `orbit`, `beacon` and `spark`, that uses the package like a real site. The end-to-end tests run on it. |
| `site` | This documentation site, built with docsp. |
| `tests` | Playwright end-to-end tests. |
| `scripts` | `lint-tokens.mjs`, `serve.mjs` (static server), `visual-compare.mjs`. |
| `docs` | Notes for maintainers, such as `visual-differences.md`. |

## Inside the package

| Package path | Content |
|---|---|
| `bin/docsp.js` | Entry point of the `docsp` command. |
| `src/cli/` | Command line parsing. |
| `src/integration/` | The Astro integration: routes, search index, code theme stylesheet. |
| `src/lib/config.ts` | Loads and validates `site.json` and `project.json`. |
| `src/lib/content.ts` | Reads the content and builds one entry per URL. |
| `src/lib/markdown.ts` | Markdown pipeline and directives. |
| `src/lib/urls.ts` | URL scheme. |
| `src/lib/openapi.ts` | OpenAPI to page data and request samples. |
| `src/lib/scip.ts`, `symbols.ts`, `nm.ts`, `tla.ts`, `symbol-site.ts` | Symbol index. |
| `src/lib/theme.ts`, `color.ts`, `theme-css.ts` | Theme resolution and contrast checks. |
| `src/lib/code-themes.ts`, `highlight.ts` | Code highlighting and code themes. |
| `src/components/`, `src/layouts/` | Astro components and page layouts. |
| `src/i18n/` | Interface strings, `en.ts` and `it.ts`. |
| `src/tokens/source.ts` | Design tokens, the single source. |
| `schema/` | JSON Schemas of the configuration files. |
| `docs/` | `configuration.md` (generated from the schemas) and `token-map.md`. |

The token pipeline is described in [Design tokens](./design-tokens.md).

## Everyday commands

From the repository root:

```terminal
$ pnpm install
$ pnpm build:pkg
$ pnpm dev
```

| Command | Effect |
|---|---|
| `pnpm build:pkg` | Compiles the package with TypeScript into `packages/docsp/dist/`. The CLI runs from there, so rebuild after changing `src/lib`, `src/cli` or `src/integration`. |
| `pnpm dev` | Builds the package, then starts the example site with live reload; catalog at `/_catalog/`. |
| `pnpm check` | Builds the package and runs `docsp check` on the example site. |
| `pnpm build` | Builds the package and the example site into `examples/site/dist/`. |
| `pnpm --filter docsp-site dev` | This documentation site with live reload, after `pnpm build:pkg`. |
| `pnpm --filter docsp-site build` | This site into `site/dist/`. |

## Writing interface strings

Interface text lives in `src/i18n/en.ts` and `src/i18n/it.ts`; every key must exist in both. Use sentence case,
buttons are a verb with its object, and confirmations are in the past tense and state the fact ("Page copied as
Markdown").

## Changing the configuration schema

Edit `packages/docsp/schema/*.json`, then regenerate the reference:

```terminal
$ pnpm --filter @fabricators/docsp docs:config
```

CI fails when `packages/docsp/docs/configuration.md` does not match the schemas. This site's
[Configuration reference](../configuration/reference.md) is copied from that file by `site/scripts/config-reference.mjs`
at every check, build and dev run, so it never needs a manual edit.
