Configuration

Plugin options

Pass options to starlightCompass() in your Starlight configuration:

astro.config.mjs

starlight({
  plugins: [
    starlightCompass({
      ask: true,
      audit: { failOn: "warning" },
      badges: true,
      devToolbar: true,
      provider: typesafe({ model: "jev-1.13.0" }),
      rules: [diataxis({ minConfidence: 0.7 })],
    }),
  ],
});

ask

Type: boolean | object
Default: false

Adds an “Ask the docs” button with a sparkle icon next to the search field, which opens a form linking readers to the pages that answer their question. See Let readers ask the docs.

The option needs an Astro adapter and a typesafe() or openaiCompatible() provider. It adds an endpoint and replaces Starlight’s Search component, so the button is skipped with a warning when you already override it. Set it to true to use the defaults, or pass an object:

ask: { maxPages: 3, minProbability: 0.3, rateLimit: 20, route: "/api/ask" }

ask.maxPages

Type: number
Default: 3

The maximum number of pages returned for a question, most likely first.

ask.minProbability

Type: number (between 0 and 1)
Default: 0.3

The probability that a page helps to answer the question above which it is returned.

ask.rateLimit

Type: number
Default: 20

The maximum number of questions per client address and minute. The limit lives in the memory of the server, so hosts with several instances limit each of them. Use 0 to disable it.

ask.route

Type: string
Default: "/api/ask"

The pathname of the endpoint answering questions.

audit

Type: object

Options for audits.

audit.failOn

Type: "error" | "warning" | "never"
Default: "error"

The lowest finding level that fails an audit. With "never", audits only report findings.

badges

Type: boolean
Default: true

Whether to show a documentation type badge below the title of pages declaring a diataxis type. The badge replaces Starlight’s PageTitle component, so it is skipped with a warning when you already override it.

devToolbar

Type: boolean
Default: true

Whether to add the Compass app to the Astro dev toolbar. The app is only added when the provider is configured, e.g. when its API key is set.

provider

Type: CompassProvider

The provider answering the questions of every rule, e.g. typesafe() or openaiCompatible(). The option is required, because Compass has no default provider. See Providers and Getting Started.

rules

Type: CompassRule[]
Default: [diataxis()]

The rules reviewing every page. Setting this option replaces the default rules. See Rules.

Environment variables

Compass reads environment variables from the shell and from .env, .env.local, .env.[mode] and .env.[mode].local files in the project root, like Vite. Variables set in the shell take precedence.

STARLIGHT_COMPASS_AUDIT

Set to 1 or true to run an audit at the end of astro build. The build fails if the provider is not configured, e.g. because its API key is missing.

TYPESAFE_API_KEY

The API key read by the typesafe() provider.

OPENAI_API_KEY

The API key read by the openaiCompatible() provider.

Frontmatter

Extend your docs schema with compassSchema() from starlight-compass/schema to add the following fields:

src/content.config.ts

docsSchema({ extend: compassSchema() });

diataxis

Type: "tutorial" | "how-to" | "reference" | "explanation" | false

The documentation type the page is meant to be, checked by the diataxis rule and shown in a badge. Set it to false to skip the rule for this page. The quality() rule also uses it to pick the rubrics that apply to the page.