Skip to content
docsp
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:

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 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.

↑ ↓ to move↵ to openSearching docsp