Configuring the printing press

Use a configuration file to keep things clean and tidy.

printing press can be configured with printing-press.yaml or printing-press.yml.

The CLI looks for the config file…

  • Next to the input file or directory
  • In the current working directory

You can also pass a config explicitly:

ppress --config ./printing-press.yaml ./services

CLI flags take precedence over config values.

No-argument API catalog builds

When config includes scan.root, you can run ppress without a positional argument:

scan:
  root: ./services
ppress

Relative paths in config are resolved from the config file directory.

Example config

title: Train Travel API Catalog
description: API documentation for train travel services.
output: ./api-docs
publish: true
theme: dark
metrics: true

scan:
  root: ./services
  include:
    - "**/*.yaml"
    - "**/*.json"
  ignoreRules:
    - "**/vendor/**"
    - "**/testdata/**"

grouping:
  noiseSegments:
    - specs
    - openapi
  serviceOverrides:
    - pattern: "services/bookings/**"
      value: bookings
  displayNameOverrides:
    - pattern: "services/bookings/**"
      value: Bookings
  versionOverrides:
    - pattern: "**/v2/**"
      value: v2

build:
  mode: fast
  maxPools: 4
  workersPerPool: 2
  maxPatternRepeatBudget: 32
  maxGeneratedStringBytes: 4096
  maxGeneratedMockBytes: 65536
  llmAggregateSpecSizeThresholdBytes: 262144
  llmMaxAggregateFileBytes: 524288
  llmGenerateMonoliths: auto
  disableSkippedRendering: true

footer:
  enabled: true
  url: https://pb33f.io/
  linkTitle: pb33f
  content: Generated with printing press.

state:
  namespace: train-travel-catalog
  sqlite:
    path: ./.printingpress-state.db

Top-level fields

Field What it controls
title API title for single-spec builds, or catalog title for catalog builds.
description Catalog description.
output Output directory.
baseURL Base URL for generated links.
basePath Base path for resolving local file references.
theme Terminal theme: dark, roger, or tektronix.
publish Same as --publish.
serve Same as --serve.
port Serve mode port.
disableExport Disable local preview archive export controls.
noHTML Skip HTML output.
noLLM Skip LLM output.
noJSON Skip JSON artifact output.
noLogo Disable the terminal banner.
debug Stream build logs live.
metrics Show live aggregate runtime metrics while rendering.

Scan fields

scan.root tells printing press where to discover OpenAPI specs for catalog builds.

scan.include narrows the files that can be discovered. If it is omitted, every candidate .yaml, .yml, and .json file can be considered.

scan.ignoreRules excludes paths.

Patterns can use recursive ** matching.

Grouping fields

Use grouping when the default service/version detection is close, but your repo layout needs a nudge.

Field What it controls
noiseSegments Directory names to skip when guessing service names.
serviceOverrides Force a service key for matching paths.
displayNameOverrides Force the visible service name for matching paths.
versionOverrides Force a version label for matching paths.

Override entries use pattern and value.

Build fields

build:
  mode: fast
  maxPools: 4
  workersPerPool: 2
  maxPatternRepeatBudget: 32
  maxGeneratedStringBytes: 4096
  maxGeneratedMockBytes: 65536
  llmAggregateSpecSizeThresholdBytes: 262144
  llmMaxAggregateFileBytes: 524288
  llmGenerateMonoliths: auto
  disableSkippedRendering: true

mode can be full, fast, or watch.

maxPools controls the maximum number of concurrent render pools.

workersPerPool controls the core budget per render pool.

maxPatternRepeatBudget, maxGeneratedStringBytes, and maxGeneratedMockBytes tune generated mock ceilings. Leave them unset, or set the matching CLI flag to 0, to use renderer defaults.

llmAggregateSpecSizeThresholdBytes, llmMaxAggregateFileBytes, and llmGenerateMonoliths tune aggregate LLM output for large catalogs. llmGenerateMonoliths accepts auto, always, or never.

disableSkippedRendering hides skipped-render warnings in generated catalog pages.

footer:
  enabled: true
  url: https://pb33f.io/
  linkTitle: pb33f
  content: Generated with printing press.

Set enabled: false to remove the generated footer.

State fields

Catalog builds use a small SQLite state database for incremental builds.

By default, the database is written under the output directory as .printingpress-state.db.

Use state.namespace and state.sqlite.path when you need a stable state key or a custom database location.