Configuration

Complete reference for boringdocs.yaml configuration options.

Full Example

# boringdocs.yaml
project:
  name: my-api
  version: 1.0.0

code:
  paths:
    - src/
    - lib/
  exclude:
    - "**/*.test.ts"
    - "**/*.spec.ts"
    - "**/node_modules/**"
  languages:
    - typescript
    - javascript

docs:
  paths:
    - docs/
    - README.md
    - CHANGELOG.md
  format: markdown    # markdown | openapi | jsdoc | auto

rules:
  - endpoint-must-have-description
  - response-schema-must-match
  - param-must-match
  - no-orphaned-code
  - no-orphaned-docs
  - example-must-compile

drift:
  threshold: warning
  baseline: .boringdocs/baseline.json

sync:
  auto_fix: false
  add_missing_stubs: true
  remove_orphans: false

ci:
  fail_on: error
  format: text

output:
  format: text        # text | json | markdown
  colors: true
  verbose: false

code.paths

Glob patterns for source code directories. All files matching these patterns will be parsed.

code.exclude

Glob patterns for files to exclude from parsing. Test files and dependencies are excluded by default.

docs.paths

Glob patterns for documentation files and directories.

docs.format

Documentation format. Use auto to detect based on file extension.

rules

List of validation rules to apply. Can be built-in rule names or custom rule definitions:

rules:
  - endpoint-must-have-description           # built-in
  - name: custom-rule                        # custom
    scope: endpoints
    condition: "path.startsWith('/v2/')"
    severity: warning
    message: "v2 endpoints need migration docs"

Environment Variables

All config values can be overridden with environment variables:

BORINGDOCS_FAIL_ON=warning boringdocs check
BORINGDOCS_FORMAT=json boringdocs check