How to Set Up Traceability for a New Project

This guide covers adding Antora Tracer to a project — whether greenfield or existing Antora site.

Choose a preset

Start by picking the preset that matches your domain. Four presets ship with the extension:

Preset Best for

requirements-engineering

Systems and software engineering with five roles and three matrices

agile

Scrum teams with epics, features, user stories, tasks, bugs, and tests

medical-iec62304

Medical device software compliant with IEC 62304, with risk and hazard tracking

minimal

Getting started and prototypes — only requirements and tests

For full details on each preset’s roles, relations, and matrices, see Presets Reference.

Add the extension to your playbook

In your antora-playbook.yml, add the extension entry:

antora:
  extensions:
    - require: @antora-tracer/core/antora-extension
      config:
        preset: requirements-engineering

If you need custom configuration, point to a traceability.yml file instead:

antora:
  extensions:
    - require: @antora-tracer/core/antora-extension
      config:
        configPath: ./config/traceability.yml

See Configuration Reference for all playbook options.

Verify the setup

Build your site:

npx antora antora-playbook.yml

The build should complete without errors. The example playbook writes generated files to .tracer/traceability/ under Antora’s configured output directory. Other projects use traceability/ by default; set outputDir to choose another location. Matrix links in navigation resolve through Antora attachments under _attachments/traceability/, independent of outputDir.

At this stage the matrices are empty because you haven’t written any items yet. Continue to How to write traceable items.

Add navigation links to traceability output

By default, the extension adds each generated HTML matrix to a "Traceability" section in site navigation. It reuses an existing "Traceability" section and skips matrix links already present. CSV files are not added to navigation. To disable automatic matrix navigation, set includeInNavigation:

antora:
  extensions:
    - require: @antora-tracer/core/antora-extension
      config:
        preset: requirements-engineering
        includeInNavigation: false

Go further

Once your project is set up, you may want to: