On this page
Commands
docsp dev, build and check, with their options and exit codes.
docsp <command> [options]| Command | What it does |
|---|---|
docsp dev |
Starts the Astro development server. Changes to Markdown, YAML and CSS files under a project reload the page. The component catalog is always on at /_catalog/. |
docsp build |
Builds the static site into dist/ and writes the search index into dist/pagefind/. |
docsp check |
Validates site.json and every project.json, checks the contrast of every project color and reads every page, without building. |
Options
| Option | Commands | Effect |
|---|---|---|
--root <dir> |
all | Folder that holds site.json. Default: the current folder. |
--port <n> |
dev |
Port of the development server. Default: Astro's port, 4321. |
--catalog |
build |
Adds the component catalog at /_catalog/ to the build output. |
--help, -h |
all | Prints the usage. |
Options may come before or after the command: docsp --root site build and docsp build --root site are the same.
Exit codes
check and build exit with 1 when the configuration or the content is not valid, and print every problem they
found. Each line names the file, the field and the expected value:
Configuration is not valid:
- rocket/project.json: "theme.grays" is "warm-ish", expected one of "warm", "cool", "neutral".
- rocket/project.json: "colour" is not a known field. Remove it or check the spelling.Content problems name the Markdown file:
Content is not valid:
- rocket/docs/en/guides/quickstart.md: frontmatter "title" is required.
- rocket/docs/en/howto/setup.md: folder "howto" is not a section id in nav.sections of rocket/project.json.A command without arguments prints the usage and exits with 1. An unknown command does the same.
What check covers
check runs in two stages and reports every problem of a stage at once:
- Configuration: both JSON files against the published schemas, then project ids, section ids,
versions.current, logo and font files,theme.cssand the contrast of every project color in light and dark mode (see Theming). - Content, only when the configuration is valid: every page, its frontmatter, section folder and directives, the release notes, the OpenAPI files and the symbol indexes.
It prints the lowest theme contrast of each project and the page count.
Some errors appear only in build. check does not render pages. An unknown icon name in a :::feature card, for example, passes check and fails
build. Run both in CI.
Warnings
Settings the schema accepts but docsp does not implement yet print a warning in check and build:
analytics with a provider other than none, nav.cta and api.tryIt. They have no effect.