# 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](../configuration/theming.md)).
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.
