On this page
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.
Everyday commands
From the repository root:
$ 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:
$ pnpm --filter @fabricators/docsp docs:configCI fails when packages/docsp/docs/configuration.md does not match the schemas. This site's
Configuration reference 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.