API and audit settings

Configure OpenAPI sources, generated references, focused contracts, and local validation. These keys belong in docs.config.yaml or an included configuration file. For file composition and validation commands, see Configure your project. Use the configuration index to find another setting.

apis

A mapping from API ID to its source and operations. See API references and focused contracts.

One authored reference page for one operation. The spec stays private:

payments:
  source: { kind: file, path: ../apis/payments/openapi.yaml }
  operations:
    - id: payments.create
      sourceOperationId: createPayment
      reference: reference.create-payment

Publish the spec, a focused contract per page, and the API catalog. This also needs site.origin:

payments:
  source: { kind: file, path: ../apis/payments/openapi.yaml, publish: true }
  discovery:
    endpoint: https://api.example.com
  operations:
    - { id: payments.create, sourceOperationId: createPayment, reference: reference.create-payment }

Keep the spec private but publish focused contracts:

payments:
  source: { kind: file, path: ../apis/payments/openapi.yaml, focused: true }
  operations:
    - { id: payments.create, sourceOperationId: createPayment, reference: reference.create-payment }

Generate reference pages for every operation except two:

payments:
  source: { kind: file, path: ../apis/payments/openapi.yaml }
  generateReferences:
    pathPrefix: /api-reference/payments
    exclude: [internalReconcile, debugEcho]

Give the v2 publication its own spec. The top-level source covers the default publication:

payments:
  source: { kind: file, path: ../apis/payments/v1.yaml }
  publications:
    - channel: production
      version: v2
      source: { kind: file, path: ../apis/payments/v2.yaml, publish: true }
  operations:
    - { id: payments.create, sourceOperationId: createPayment, reference: reference.create-payment }

audit

Optional local audit settings. Run shoalrun check [config] or shoalrun audit [config] to execute configured tests and build a temporary site. The checks compare API representations, inspect focused contracts, and validate local links. check prints readable results (--json selects JSON); audit returns JSON. Both exit with code 1 on failure.

audit:
  tests:
    - id: project-tests
      run: [node, --test, scripts/docs.test.mjs]
  api: true
  focusedContracts: true
  links: true

audit.tests is the integration point for external test suites. We recommend Doc Detective for documentation behavior tests; any command that exits nonzero on failure can be used. Each test needs a unique lowercase id and a nonempty run argument list. The first argument names the executable; the rest are passed without a shell. Commands run from the directory containing docs.config.yaml, so use project-relative paths. The api, focusedContracts, and links switches default to true. Set any to false to skip that group. The site build always runs because it checks the complete project and supplies focused contracts. See audit a docs project for a Doc Detective example, execution order, output, timeouts, and limits.

For snapshot validation, declare local check dependencies with optional inputs paths relative to the directory containing docs.config.yaml:

audit:
  tests:
    - id: formatting
      run: [vale, --config=../format.ini, content]
      inputs: [../format.ini, ../styles]

The snapshot copies declared files and directories within the project parent. It rejects missing inputs, symlinks, credentials, dependency folders, and paths outside that boundary. Directory declarations also track added and deleted files for freshness. Declare the configuration's supporting files too; Shoalrun does not infer dependencies from command arguments. Ordinary check and audit commands still run in the original project.

Agent evaluation reports

audit.evals opts into checking a reviewed task report after the audit's temporary build. Set tasks to a YAML or JSON task file and report to a JSON result file. Both paths resolve relative to the file declaring them. Optional run is a nonempty command/argument list. It runs without a shell from the root config directory after a successful build. The timeout is two minutes; environment variables supply eval paths and digests. It can call external services and write the report; a nonzero exit fails independently of report validation. No evaluator is built into Shoalrun. See evaluate agent tasks for the report format, environment variables, and CLI commands.

Related reading

Read first

• Organize project configuration — Learn how files combine and how to validate configuration changes.

Reference while working

• Configuration reference — Find configuration settings in another topic.