Skip to content
docsp
On this page

Commands

docsp dev, build and check, with their options and exit codes.

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

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

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

  1. Configuration: both JSON files against the published schemas, then project ids, section ids, versions.current, logo and font files, theme.css and the contrast of every project color in light and dark mode (see Theming).
  2. 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.

Warning:

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.

↑ ↓ to move↵ to openSearching docsp