On this page
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.
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 buildWhat the commands catch
| Problem | check |
build |
|---|---|---|
Invalid or unknown field in site.json or project.json |
yes | yes |
| Project color below 4.5 | 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.