Skip to content

User configuration

TopMark runtime configuration may be provided through:

  • topmark.toml
  • pyproject.toml ([tool.topmark])
  • CLI overrides
  • API overlays

Configuration is resolved through layered discovery, normalization, and precedence rules. Higher-precedence layers override lower-precedence layers.

Note

The canonical vocabulary used throughout the documentation is defined in Terminology and Canonical Vocabulary.

CLI, configuration, and API value spelling

Configuration keys use consistent naming across the CLI, API, and TOML configuration surfaces. Some options accept predefined multi-word values such as add_only or whitespace_empty.

TopMark uses different spelling conventions depending on the interface: CLI examples prefer hyphenated forms for readability, while TOML configuration, Python API values, and machine-readable output use canonical underscore forms.

Note

CLI spelling vs configuration/API spelling

TopMark uses hyphenated spelling for CLI option names:

topmark check --header-mutation-mode=add-only

For multi-word option values, the CLI accepts both hyphenated and canonical underscore forms:

topmark check --header-mutation-mode=add-only
topmark check --header-mutation-mode=add_only

TOML configuration, Python API values, and machine-readable output use the canonical underscore form:

[policy]
header_mutation_mode = "add_only"

CLI option names themselves do not accept underscores. Use --header-mutation-mode, not --header_mutation_mode.

Unless otherwise noted, configuration and policy values shown throughout this page use the canonical TOML/API/machine-readable underscore form.

File type identifiers

TopMark accepts file type identifiers in local form, such as python, or qualified form, such as topmark:python.

Local identifiers are accepted only when unambiguous. Internally, TopMark normalizes identifiers to canonical qualified file type identities before filtering, runtime resolution, policy evaluation, diagnostics, and registry lookup.

See file-type filtering for the full identifier contract.

File type identifiers participate in stable runtime behavior such as:

  • include_file_types
  • exclude_file_types
  • policy_by_type
  • CLI file-type filters
  • API file-type filters and policy overlays

File-type filters

File-type filters allow restricting runtime processing to a selected subset of file types.

Example using local identifiers:

[files]
include_file_types = ["python", "markdown"]

Equivalent configuration using canonical qualified keys:

[files]
include_file_types = ["topmark:python", "topmark:markdown"]

Exclude filters work the same way:

[files]
exclude_file_types = ["topmark:yaml"]

[NOTE] Internally, TopMark normalizes configured file type identifiers to canonical qualified identities before filtering, runtime resolution, policy evaluation, diagnostics, and registry lookup.

Per-file-type policy

policy_by_type allows file-type-specific policy overrides for selected file types.

Example using a local identifier:

[policy_by_type.python]
header_mutation_mode = "update_only"

Equivalent configuration using canonical qualified keys:

[policy_by_type."topmark:python"]
header_mutation_mode = "update_only"

Both forms are accepted when the local identifier resolves unambiguously.

Internally, TopMark stores and resolves per-file-type policies using canonical qualified file type identities.

Example: Different policy per file type

[policy]
header_mutation_mode = "add_only"

[policy_by_type."topmark:python"]
header_mutation_mode = "update_only"

[policy_by_type.markdown]
allow_content_probe = false

In this example:

  • the global default policy uses add_only
  • Python files override this with update_only
  • Markdown files disable runtime content probing

Ambiguous identifiers

When more than one registered file type shares the same local identifier, TopMark requires the canonical qualified form.

For example, if both:

  • topmark:python
  • acme:python

are registered, then:

include_file_types = ["python"]

is ambiguous.

Use:

include_file_types = ["topmark:python"]

instead.

Ambiguous identifiers are ignored diagnostically during configuration normalization and staged configuration-loading validation.

Unknown and malformed identifiers

Unknown identifiers are ignored diagnostically during configuration normalization and staged configuration-loading validation.

Malformed qualified identifiers are also ignored diagnostically during configuration normalization and staged configuration-loading validation.

Examples of malformed identifiers:

:python
topmark:
topmark:python:extra

CLI and API parity

CLI options, TOML configuration, API overlays, and runtime policy evaluation all share the same file type identity semantics.

Examples:

topmark check --include-file-types python .

topmark check --include-file-types topmark:python .

api.check(
    paths=[repo],
    include_file_types=["topmark:python"],
)

Runtime configuration model

TopMark intentionally separates:

  1. TOML-source loading
  2. staged configuration-loading validation
  3. layered configuration deserialization and merging
  4. runtime configuration resolution
  5. runtime overlay application
  6. runtime policy evaluation
  7. runtime pipeline gatekeeping and execution

Reporting, API surfaces, and machine-readable output expose a flattened compatibility view derived from these internal runtime stages.

This layered runtime configuration model keeps behavior deterministic while preserving stable configuration, policy, diagnostics, and machine-readable compatibility contracts.

See also