Configuration Reference

Playbook Options

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

antora:
  extensions:
    - require: @antora-tracer/core/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 and the per-version graph.json snapshot. 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 tracer:graph[] and tracer:graph-coverage[]. 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

renderSuperseded

boolean

true

When true (default), superseded item blocks render with a superseded marker. Set to false to omit superseded blocks and their supersedes links from rendered output (display-only — the graph and matrices are unaffected)

generateOverview

boolean

true

Generate the traceability overview page (totals, per-role statistics, a superseded-items list, and the dangling-reference worklist) into the output directory

overviewTarget

string

traceability/overview.html

Attachment relative path for the generated overview, so it is navigable via xref:attachment$…​

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.

When matrix generation is enabled, the extension also registers a per-version graph.json snapshot as a site attachment under traceability/graph.json. The snapshot contains every item and relationship of that component version in the canonical { format, component, version, items, relationships } shape, with per-item scope fields but no per-page pubUrl. It gives each published version a machine-readable record of its traceability graph.

Build version

On every build, the extension computes the version string git describe --tags --always --dirty from the playbook directory and exposes it under one key in two channels:

  • site.keys.git_describe — for HTML UI templates ({{site.keys.git_describe}})

  • asciidoc.attributes.git_describe — for AsciiDoc content and the PDF/DOCX backends (3191517)

When the build runs outside a git repository, neither key is set and the build continues unchanged. No configuration is required. See How to show the build version in the footer.

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/core/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/core/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

tracer:
  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)

tracer:
  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 addresses:REQ-001[], or a requirement may write addressed_by:DES-001[]. 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.

Supersession

A baselined item is superseded rather than edited in place. The successor declares supersedes (reverse superseded_by) to the item it replaces.

relations:
  requirement:
    requirement:
      supersedes:
        reverse: superseded_by

An item is superseded when one or more incoming supersedes relationships target it — no status attribute is required. Splits (one predecessor, several successors) and merges (one successor, several predecessors) are supported. Self-supersession, duplicate links, and cycles are validation errors.

Current-state matrices omit superseded items. Functional links to a superseded item remain visible and are marked for review. See supersession check for the read-only impact report.

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

roleGuidance

Per-role authoring guidance for AI agents and humans. Each entry maps a role to an AsciiDoc page describing how to write items of that role, plus an optional ID prefix fallback:

roleGuidance:
  requirement:
    page: guidance/requirement.adoc
    idPrefix: REQ
  design:
    page: guidance/design.adoc
    idPrefix: ARC
Key Type Description

page

string

Path to an AsciiDoc page with the role’s authoring guidance, resolved relative to the file that declares it

idPrefix

string

ID prefix fallback (advisory, never authoritative)

Built-in presets ship default guidance pages. A project’s roleGuidance overrides the preset per role. Resolve guidance from the CLI with antora-tracer role-guidance <role>.

idAllocation

Opt-in remote ID allocation for the next-id command. When set, next-id requests the next ID from a shared allocator instead of scanning local files:

idAllocation:
  endpoint: https://ids.example.com   # required, HTTP(S) URL
  token: ${ID_ALLOC_TOKEN}            # optional bearer token

endpoint must be a non-empty HTTP(S) URL. token, when set, is sent as Authorization: Bearer <token>.

Both values support environment-variable interpolation, so secrets stay out of the committed file. An unset variable fails configuration loading. The CLI loads a .env file from the working directory at startup, so you can keep the token there instead of exporting it.

When endpoint is set, next-id fails closed: an unreachable allocator, a non-2xx response, or a malformed body exits with an error rather than falling back to a local ID. A 401 or 403 response is reported as an authentication failure. Pass --local to force the local scan regardless.

Absent idAllocation, next-id keeps its local max+1 behavior unchanged.

The allocator itself is the separate ID allocation server package.

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