Skip to content
docsp
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.

YAML.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
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

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.

↑ ↓ to move↵ to openSearching docsp