Configuration Reference

Playbook Options

Configure the extension in your Antora playbook (antora-playbook.yml or antora.yml):

antora:
  extensions:
    - require: antora-tracer/antora-extension
      config:
        preset: requirements-engineering
        # ... additional options ...
Option Type Default Description

enabled

boolean

true

Set to false to disable the extension without uninstalling

preset

string

requirements-engineering

Built-in preset name. Overridden by configPath. Valid: requirements-engineering, agile, medical-iec62304, minimal

configPath

string

—

Path to a custom traceability.yml file. Takes precedence over preset

outputDir

string

traceability

Output directory relative to the site output root

generateMatrices

boolean

true

Generate traceability matrices. Set to false for Neo4j-only usage

matrixFormats

string[]

['html']

Output formats. Valid: html (interactive), csv (data)

includeInNavigation

boolean

true

Add traceability pages to the Antora site navigation

krokiImageFormat

string

svg

Image format for Kroki URLs generated by traceability:graph[] and `. Valid: `svg, png

krokiServerUrl

string

https://kroki.io

Base URL for Kroki image generation. Overridden by the KROKI_SERVER_URL environment variable

allowDuplicateIds

boolean

false

When false (default), the build fails if two items define the same ID. Set to true to log a warning and keep the first definition instead

The KROKI_SERVER_URL environment variable overrides the krokiServerUrl option. When set, it is used as the Kroki server base URL instead of the configured value or the default https://kroki.io.

Vale Extension

The bundled antora-vale extension runs the Vale prose linter against the source AsciiDoc of the complete content catalog during the build. It is opt-in: register it in the playbook to enable it.

antora:
  extensions:
    - require: antora-tracer/antora-vale
      valeConfig: .vale.ini
      minLevel: warning
Option Type Description

valeConfig

string

Path to the Vale configuration file (.vale.ini), resolved relative to the playbook directory.

minLevel

string

Minimum severity that fails the build: suggestion, warning (default), or error. Findings below this level are logged, not fatal.

Prerequisites: the vale and asciidoctor executables must be on PATH. If either is missing, the build fails with an actionable message. A starter style is shipped at node_modules/antora-tracer/lib/src/vale/; copy it into your project and reference it from your .vale.ini, or write your own rules.

Source-layout rules such as one sentence per line are not enforced by Vale. Use scripts/check-one-sentence-per-line.js for that.

traceability.yml Schema

When using a custom configuration, create a traceability.yml file:

extends: requirements-engineering   # optional

roles:
  - requirement
  - design
  - test

relations:
  design:
    requirement:
      addresses:
        reverse: addressed_by
  test:
    requirement:
      verifies:
        reverse: verified_by

matrices:
  - name: requirements-to-design
    description: "Forward traceability from requirements to design"
    rows: requirement
    columns: [design]
    coverageRelations:
      design: [addresses]

labels:              # optional display names
  addresses: "Addresses"

extends

traceability:
  extends: requirements-engineering

Pulls in a built-in preset as the base. Your config is deep-merged on top: - roles: appended (duplicates silently merged) - relations: merged at all levels - matrices: appended

If extends is omitted, the config is standalone — no preset is loaded.

Presets can themselves extend another preset. In a preset file, extends is a top-level field next to name and version:

name: medical-safety
version: 1.0.0
extends: requirements-engineering   (1)

traceability:
  roles:
    - use_case
1 The parent’s roles, relations, matrices, and labels are deep-merged under the child

Inheritance chains resolve transitively; circular inheritance is rejected. See Presets Reference for the preset schema.

roles

Flat list of strings. Every [item] must use a role in this list. Case-insensitive. Unknown roles generate warnings.

relations

Nested map: source_role → target_role → type → { reverse }. Each relation type is a key with a mandatory reverse — the authorable name for the same edge seen from the other side.

relations:
  design:
    requirement:
      addresses:
        reverse: addressed_by

Both names are authorable: a design may write , or a requirement may write . Either authoring stores the same canonical edge (design → requirement : addresses).

The reverse direction is allowed automatically — you do not declare requirement → design separately. Symmetric relations declare themselves as their own reverse:

relations:
  requirement:
    requirement:
      conflicts_with:
        reverse: conflicts_with

If a relation type is used that is not declared (or derived as a reverse), the extension reports an error with the allowed alternatives.

labels

Optional display-only map: type → human-readable name. Never affects graph structure, merge behavior, or validation.

labels:
  leads_to: "Leads to"
  is_derived_from: "Is derived from"

If a type has no labels entry, the humanized type name is used: underscores become spaces, sentence-cased (is_derived_from → "Is derived from").

matrices

An array of matrix definitions:

Key Type Description

name

string

Used in output filename: matrix-<name>.html and matrix-<name>.csv

description

string

Human-readable description, displayed as caption in HTML output

rows

string

Role for the row index. One row per item of this role

columns

string[]

Roles for the columns. Each cell shows items of that role related to the row item

coverageRelations

map

Which relation types count as "coverage" per column role. coverageRelations: design: [addresses, satisfies] means only addresses and satisfies from row items to design items count

Configuration Resolution

When both preset and configPath are provided, configPath takes precedence:

1. If configPath is set → load user YAML file 2. If configPath has extends → load the referenced preset, then deep-merge 3. If only preset is set → load the built-in preset 4. If neither → error

The resolved configuration is memoized — loaded once and shared across all components.

Related