Skip to content
Starlight Compass

This only links to pages of the documentation. It does not write answers.

Audit your docs in CI

How-to guide

An audit reviews every page at the end of a build and fails the build when it finds errors. Audits only run when the STARLIGHT_COMPASS_AUDIT environment variable is set, so local builds and deployments stay offline.

Prerequisites

Section titled “Prerequisites”
  • A Starlight site with Compass and a provider set up, where pages declare their type with the diataxis frontmatter field.
  • The API key of your provider, stored as a secret in your repository settings. The workflow below assumes a TypeSafe key named TYPESAFE_API_KEY. Use the variable of your provider otherwise, e.g. OPENAI_API_KEY.

Add the audit to your workflow

Section titled “Add the audit to your workflow”

  1. Add a workflow that builds your docs with STARLIGHT_COMPASS_AUDIT=1. For example, with GitHub Actions and pnpm:

    .github/workflows/docs-audit.yaml
    name: Docs audit
    

    on:
      pull_request:
    

    jobs:
      audit:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v5
          - uses: pnpm/action-setup@v4
          - uses: actions/setup-node@v5
            with:
              cache: pnpm
          - run: pnpm install
          - uses: actions/cache@v4
            with:
              path: node_modules/.astro/starlight-compass
              key: starlight-compass-${{ github.sha }}
              restore-keys: starlight-compass-
          - run: pnpm build
            env:
              STARLIGHT_COMPASS_AUDIT: 1
              TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}

    Caching the starlight-compass directory in Astro’s cacheDir means only changed pages are sent to the provider.

  2. Open a pull request. The build log groups errors and warnings by file, for example:

      ╭─ src/content/docs/guides/deploy.md
      ·
    ✗ | Declared as a tutorial but reads like a how-to guide (84% confidence).
      · ╰── diataxis
    

      ╭─ src/content/docs/concepts/routing.md
      ·
    ⚠ | Mixes several documentation types and could be split into separate pages (72% probability).
      · ╰── diataxis
    

    ╭─                                         ─╮
    · Found 1 error and 1 warning in 2 files. ·
    ╰─                                         ─╯

    In GitHub Actions, the same findings also appear as a table in the job summary, with links to the files.

Choose what fails the build

Section titled “Choose what fails the build”

An audit fails on errors by default. To also fail on warnings, or to only report findings, set the audit.failOn option. Add more rules to audit more than the documentation type, e.g. quality() or duplicates(), which report warnings.