# CI checks

The checks to run in the CI of a repository that holds docsp content, with a GitHub Actions example.

A content repository needs two commands in CI: `docsp check` for fast feedback on configuration and content, and
`docsp build`, which also renders every page and catches errors that only appear then, such as an unknown icon name.

```yaml title=".github/workflows/docs.yml"
name: Docs

on:
  pull_request:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Page dates come from git history.
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx docsp check
      - run: npx docsp build
```

## What the commands catch

| Problem | `check` | `build` |
|---|---|---|
| Invalid or unknown field in `site.json` or `project.json` | yes | yes |
| Project color below 4.5:1 | yes | yes |
| `theme.css` with forbidden selectors or properties | yes | yes |
| Missing logo or font file | yes | yes |
| Missing `title`, unknown frontmatter field | yes | yes |
| Page folder that is not a section | yes | yes |
| Unknown block directive, `::card` without `href` | yes | yes |
| Invalid OpenAPI file | yes | yes |
| Symbol index that does not match the source | yes | yes |
| Unknown icon in `:::feature` | no | yes |
| Broken relative link or missing image | no | no |

## Add a link check

docsp does not check that relative links, card links and images resolve. Run a link checker on `dist/` after the
build. docsp writes root-relative URLs that end with `/`, so configure the checker to resolve `/` against `dist/` and
a folder URL to its `index.html`.

## Add an accessibility check

To run axe on your own pages, serve `dist/` and run Playwright with `@axe-core/playwright`, the way the docsp
repository tests its example site (`tests/site.spec.ts`).

## Keep docsp current

The configuration schemas come with the package. After an upgrade, run `docsp check` first: a removed or renamed
field shows up as an unknown field with its file.
