User Guide

Overview

The Antora Requirements Traceability Extension adds role-based traceability to your Antora documentation. Define items with a single [item] block macro, reference them through user-defined relation types, and generate traceability matrices and coverage reports — all driven by your domain model.

Key capabilities:

  • One macro for everything — [item, role=…​] replaces role-specific macros

  • User-defined roles and relations — configure your own traceability domain (requirements engineering, agile, medical, or custom)

  • Built-in presets — start with requirements-engineering, agile, medical-iec62304, or minimal

  • Matrix generation — HTML and CSV matrices per your configuration

  • Coverage reports — visual per-role coverage with status badges

  • Neo4j export — CSV and Cypher for graph queries

  • CLI — standalone processing outside Antora

  • Validation — catches invalid relations at processing time

Getting Started

Already have an Antora site? Skip to step 2.

  1. Install the extension

    npm install antora-tracer --save-dev

  2. Add it to your Antora playbook (antora.yml)

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

  3. Write items in your AsciiDoc files

    [#REQ-001, item, role=requirement]
====
User Authentication

The system shall require authentication for all protected endpoints.
====

[#IMP-001, item, role=implementation]
====
Auth Service

JWT-based authentication with token refresh.

satisfies:REQ-001[]
====

[#TEST-001, item, role=test]
====
Authentication Tests

Unit and integration tests for the auth service.

verifies:REQ-001[]
tests:IMP-001[]
====

  4. Build your site

    npx antora antora-playbook.yml

  5. Open the output

    Open <site-output>/traceability/index.html — you’ll find matrices and a coverage report.

The Traceability Model

Before you write items, understand the three concepts that define your traceability domain.

Roles

A role is a category of traceable item. Think of it as a type label: "requirement", "design", "test", "user_story", "risk_control". Roles are purely user-defined — the extension has no built-in roles. You define them in your traceability configuration, and every [item] gets a role attribute.

[#REQ-001, item, role=requirement]
[#STORY-001, item, role=user_story]
[#TEST-001, item, role=test]

Relations

A relation connects two items of specific roles. Relations are directional (source → target) and typed (satisfies, verifies, implements, etc.). Which relation types are allowed between which roles is defined in your configuration.

[#IMP-001, item, role=implementation]
====
satisfies:REQ-001[]     (1)
implements:DES-001[]    (2)
====
1 Implementation satisfies Requirement
2 Implementation implements Design

Matrices

A matrix cross-references items of one role (rows) against items of other roles (columns), counting how many of each relation type exist. Matrices are configurable — you decide which roles go on rows, which on columns, and which relation types count as "coverage."

Requirement

Design

Implementation

Test

REQ-001

DES-001

IMP-001

TEST-001

REQ-002

—

—

TEST-002

Configuration

The extension is configured through your Antora playbook.

Using a Preset

The simplest path. Pick a preset that matches your domain:

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

Four built-in presets are available:

Preset Best For

requirements-engineering

Systems & software engineering

agile

Agile/Scrum teams with user stories

medical-iec62304

Medical device software (IEC 62304)

minimal

Getting started, simple projects

See Presets Reference for the full breakdown of each preset.

Custom Configuration

For full control, point to a traceability YAML file:

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

The configuration file defines your roles, the allowed relations between them, and the matrices to generate:

traceability:
  roles:
    - requirement
    - design
    - implementation
    - test

  relations:
    requirement:
      design: [addresses, satisfied_by]
      implementation: [implemented_by]
      test: [verified_by]

    design:
      requirement: [implements]
      implementation: [realized_by]
      test: [validated_by]

    implementation:
      requirement: [satisfies]
      design: [implements]
      test: [tested_by]

    test:
      requirement: [covers, verifies]
      implementation: [tests]

  matrices:
    - name: requirements-traceability
      description: "Requirements to design, implementation, and test"
      rows: requirement
      columns: [design, implementation, test]
      coverageRelations:
        design: [addresses, satisfied_by, implements]
        implementation: [implemented_by, satisfies, implements]
        test: [verified_by, covers, verifies, tests]

Understanding the Config

Roles

A flat list of strings. Every [item] must have a role that appears in this list. Roles are case-insensitive.

Relations

A nested map: source_role → target_role → [allowed_types]. Each entry says "items with role X can use relation types [A, B, C] to point at items with role Y." If you write a relation that isn’t in this map, the extension reports an error with the allowed types.

Matrices

An array of matrix definitions. Each matrix has:

  • name — used in the output filename (matrix-<name>.html)

  • rows — the role that becomes the row index

  • columns — roles that become columns

  • coverageRelations — which relation types count as "coverage" for each column role

Relation Validation

When the extension processes your items, it validates every inline relationship against your configuration. If you write:

[#DES-001, item, role=design]
====
verifies:REQ-001[]       (1)
====
1 verifies from design to requirement — is that allowed?

The extension checks: does relations.design.requirement include verifies? If not, you get:

Error: Relation 'verifies' not allowed from 'design' to 'requirement'.
Allowed: [addresses, satisfied_by, implements]

This catches misconfigurations early and prevents invalid traceability graphs.

Playbook Options

All playbook-level configuration options:

Option Type Default Description

enabled

boolean

true

Set to false to disable the extension

preset

string

requirements-engineering

Built-in preset name; overridden by configPath

configPath

string

—

Path to a custom traceability YAML 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', 'csv']

Output formats; valid values: html, csv

includeInNavigation

boolean

true

Add traceability pages to the Antora site navigation

Writing Items

The [item] Block Macro

[#TYPE-XXX, item, role=<role>, title="TYPE-XXX — Title", status="draft"]
====
Item content. Can span multiple paragraphs.

Inline relationships go anywhere inside the block:

<relation-type>:TARGET-ID[]
<relation-type>:TARGET-ID[]
====

Attributes

Attribute Required Description

id

Yes

Unique identifier. Recommended format: ROLE-NNN (e.g., REQ-001, STORY-042)

role

Yes

Must match a role in your configuration. Case-insensitive

title

No

Display title. Defaults to the id if omitted

status

No

Free-form status: draft, reviewed, approved, implemented, deprecated

priority

No

Free-form priority: high, medium, low

Inline Relationships

A relationship is expressed as <relation-type>:<TARGET-ID>[] anywhere inside the item block. The TARGET-ID must match the id of another item.

[#IMP-001, item, role=implementation]
====
Auth Service

satisfies:REQ-001[]
implements:DES-001[]
depends_on:IMP-002[]
====

Relationship syntax:

  • Multiple targets per type: satisfies:REQ-001,REQ-002,REQ-003[]

  • Multiple types per item: write each on its own line

  • The extension validates that each relation is allowed by your config

Inline Macros Are Data Markers

Inline relationship macros (`) are always invisible in rendered output. They are pure data markers stored in the traceability graph. To display relationships in your documentation, use the `traceability:outgoing[] and traceability:incoming[] macros described below.

This keeps your source clean — type the relationship once, let the macros handle display.

The traceability:outgoing[] Macro

Place traceability:outgoing[] inside an item block to render all outgoing relationships as a formatted list:

[#ARC-001, item, role=architecture, title="ARC-001 — Project Scope"]
====
Project description...

addresses:REQ-001[]
addresses:REQ-006[]
addresses:REQ-009[]

traceability:outgoing[]
====

The macro queries the traceability graph at build time and generates AsciiDoc output — lists, tables, or inline xrefs — showing each relationship with the target’s full title.

The traceability:incoming[] Macro

Place traceability:incoming[] inside an item block to render all incoming relationships — items that reference this item from elsewhere:

[#REQ-001, item, role=requirement, title="REQ-001 — System shall..."]
====
Requirement description...

traceability:incoming[]
====

The macro displays relationships pointing TO this item, with inverse relation type labels (e.g., addresses becomes Addressed by). This is useful for seeing which architecture components, designs, or tests reference a given requirement.

Opt-in per page via document attributes:

= Architecture
:traceability-links: true
:traceability-style: list
:traceability-order: target-id
Attribute Effect

:traceability-links:

true to enable the macros. Without it, traceability:outgoing[] and traceability:incoming[] text is stripped.

:traceability-style:

list (default, bulleted list), table (AsciiDoc table), or inline (comma-separated)

:traceability-order:

target-id (default, alphabetical by ID), target-title (by title), or relation-type (grouped by type)

PDF compatibility: The macro generates standard AsciiDoc constructs (xrefs, lists, tables) — compatible with both HTML and PDF backends identically.

Role-Based Validation

The extension validates:

  1. Role exists — if role=widget and widget isn’t in your config, you get a warning: Unknown role "widget". Known roles: requirement, design, test.

  2. Relation allowed — if you write ` from a `document but your config only allows document → requirement: [contains], you get an error listing the allowed types.

  3. Target exists — if TARGET-ID doesn’t exist, you get: Target item not found: MISSING-001.

Warnings don’t block processing; errors do. Unknown roles generate warnings (graceful degradation). Invalid relations generate errors.

ID Conventions

While any unique string works, a consistent convention helps readability:

Pattern Example Convention

Role prefix

REQ-001, IMP-042, TEST-099

Two-to-four uppercase letters, hyphen, number

Hierarchical

SYS.SEC.AUTH-001

Dotted namespace

Domain prefix

PROJ-REQ-001

Project prefix

Sharing Items Across Files

Items can live in any .adoc file in your Antora component. The extension aggregates all items across all files into a single traceability graph. A requirement in modules/ROOT/pages/requirements.adoc can be referenced by an implementation in modules/impl/pages/services.adoc — as long as the IDs match.

Generated Output

After a build, generated artifacts appear in <site-output>/traceability/ (or wherever you set outputDir).

Traceability Index

traceability/index.html — a landing page with links to all matrices and the coverage report.

Matrices

One HTML and one CSV file per configured matrix:

File Description

matrix-<name>.html

HTML table with color-coded status badges

matrix-<name>.csv

CSV with header row and summary statistics

Each matrix row shows one item (from the rows role) and its related items per column role. Cells show IDs of related items, or — if none exist. All item IDs are clickable links — clicking navigates to the item’s definition in the rendered HTML documentation.

Status badges in the HTML output:

Badge Meaning

✓ Complete

At least one relationship in every column

◐ Partial

Relationships in some columns but not all

✗ Missing

No relationships at all

Matrix filenames use the matrix name from your config. With the requirements-engineering preset, you’ll see files like matrix-requirements-traceability.html and matrix-design-verification.html.

Coverage Report

traceability/coverage.html — a visual breakdown:

  • Total items per role

  • Items with at least one relationship per configured coverage relation

  • Overall coverage percentage

  • Color-coded progress bars: green (≥80%), orange (50-79%), red (<50%)

Neo4j Export

traceability/neo4j/nodes.csv and traceability/neo4j/relationships.csv — see Neo4j Export for details.

CLI Reference

The extension provides a CLI for use outside Antora:

# Display help
npx antora-tracer --help

process

Process AsciiDoc files to populate the traceability graph.

npx antora-tracer process -i docs/ --preset requirements-engineering
npx antora-tracer process -i requirements.adoc --config ./traceability.yml

Options: - -i, --input <path> — input file or directory (required) - -o, --output <path> — output directory (default: ./output) - -f, --format <format> — output format: html, csv, json (default: html) - --preset <name> — built-in preset - --config <path> — custom traceability YAML

matrix

Generate traceability matrices from processed items.

npx antora-tracer matrix -i docs/ -t requirements-traceability -f html
npx antora-tracer matrix -t requirements-traceability -f csv -o matrix.csv

Options: - -i, --input <path> — input file to process first (optional) - -t, --type <type> — matrix name from your config - -f, --format <format> — csv, html, or json (default: csv) - -o, --output <path> — output file (defaults to stdout)

validate

Validate the traceability graph for orphaned items, missing targets, and invalid relations.

npx antora-tracer validate -i docs/ --preset requirements-engineering

Options: - -i, --input <path> — input file or directory to validate - --preset <name> — built-in preset - --config <path> — custom traceability YAML

The command exits with a non-zero code if errors are found.

export neo4j

Export the graph to Neo4j-compatible formats.

npx antora-tracer export neo4j -i docs/ --format csv -o ./neo4j-export/
npx antora-tracer export neo4j -i docs/ --format cypher -o ./neo4j-export/

Options: - -i, --input <path> — input file or directory to process first - --format <format> — csv (nodes + relationships) or cypher (single script) - -o, --output <path> — output directory

stats

Display role statistics for the current graph.

npx antora-tracer stats -i docs/ --preset requirements-engineering

Output shows item counts per role and relationship counts.

preset

Manage built-in presets.

npx antora-tracer preset list                          (1)
npx antora-tracer preset show requirements-engineering (2)
npx antora-tracer preset init -n medical-iec62304 -o ./config/  (3)
1 List all available presets with descriptions
2 Show a preset’s configuration details
3 Write a preset’s traceability YAML to a file for customization

Options (init): - -n, --name <name> — preset name (required) - -o, --output <path> — output directory (default: current directory)

Presets Reference

requirements-engineering

Systems and software engineering. Five roles with comprehensive relation coverage.

Roles

requirement, design, implementation, test, document

Matrices

requirements-traceability, design-verification, implementation-coverage, test-coverage

Key relations: design → requirement [addresses, satisfies], implementation → requirement [satisfies], implementation → design [implements], test → requirement [covers, verifies], test → implementation [tests]. The requirement role defines only requirement-to-requirement relations (refines, depends_on, conflicts_with); downstream roles declare their own relations back to requirements.

agile

Agile/Scrum teams. Eight roles mapping the Scrum backlog.

Roles

epic, feature, user_story, acceptance_criterion, task, spike, bug, test

Matrices

epic-progress, story-completion, sprint-backlog, test-coverage

Key relations: epic → feature [contains], user_story → task [broken_down_into], task → user_story [implements], test → user_story [verified_by], task → bug [fixes].

medical-iec62304

Medical device software compliant with IEC 62304. Five roles with safety classification support.

Roles

system_requirement, software_requirement, software_item, software_unit, risk, hazard, mitigation

Matrices

risk-mitigation

Key relations: system_requirement → software_requirement [allocated_to], system_requirement → risk [mitigated_by], software_requirement → software_requirement [refines, depends_on], mitigation → risk [mitigates].

minimal

Two roles — the simplest possible setup. Good for learning and prototypes.

Roles

requirement, test

Matrices

requirements-tests

Key relations: test → requirement [covers], test → requirement [verified_by], requirement → requirement [depends_on].

Initializing a Custom Preset

Start from a built-in preset, then customize:

npx antora-tracer preset init -n requirements-engineering -o ./config/

This writes the preset’s YAML to ./config/traceability.yml. Edit it to add roles, change relations, or add matrices, then point your playbook at it with configPath.

Neo4j Export

CSV Export

Generates two files:

  • nodes.csv — all items with id, role, title, content, and attributes

  • relationships.csv — all relationships with source, target, and type

Import into Neo4j:

LOAD CSV WITH HEADERS FROM 'file:///nodes.csv' AS row
CREATE (n:Item {id: row.id, role: row.role, title: row.title});

LOAD CSV WITH HEADERS FROM 'file:///relationships.csv' AS row
MATCH (a:Item {id: row.fromId}), (b:Item {id: row.targetId})
CREATE (a)-[r:RELATES {type: row.type}]->(b);

Cypher Export

Generates a single import.cypher file with CREATE statements for all nodes and relationships. Can be executed directly in Neo4j Browser or via cypher-shell.

Example Queries

Once imported into Neo4j, ask questions like:

// Requirements without any implementation or test coverage
MATCH (r:Item {role: 'requirement'})
WHERE NOT EXISTS {
  MATCH (r)<-[:RELATES]-(:Item)
}
RETURN r.id, r.title ORDER BY r.id

// Full traceability chain: requirement → design → implementation → test
MATCH path = (r:Item {role: 'requirement'})<-[:RELATES]-(d:Item {role: 'design'})
           -[:RELATES]->(i:Item {role: 'implementation'})<-[:RELATES]-(t:Item {role: 'test'})
RETURN r.id, d.id, i.id, t.id

// Impact analysis: what depends on REQ-001?
MATCH (r:Item {id: 'REQ-001'})
OPTIONAL MATCH (r)<-[:RELATES]-(d:Item {role: 'design'})
OPTIONAL MATCH (d)-[:RELATES]->(i:Item {role: 'implementation'})
RETURN r.id, collect(d.id) as designs, collect(i.id) as implementations

Each preset also ships with example Cypher queries in its documentation. View them with:

npx antora-tracer preset show requirements-engineering

Recipes & Patterns

Common Setups

Requirements-driven development:

Use requirements-engineering preset. Define requirements first, then implementations, then tests. Each implementation satisfies a requirement; each test verifies a requirement.

Agile backlog traceability:

Use agile preset. Epics contain features, features break down into user stories, user stories break down into tasks. Tests verify stories; tasks fix bugs.

Regulatory compliance:

Use medical-iec62304 preset. System requirements drive software requirements, which are implemented by software items and verified by tests. Risk controls trace to software requirements.

Just getting started:

Use minimal preset. Requirements and tests only. Add more roles as your traceability needs grow.

Multi-Component Projects

If your Antora site has multiple components, each with its own .adoc files, items are aggregated across all components automatically. Use consistent ID conventions across components to ensure relationships resolve correctly.

Incremental Adoption

  1. Start with minimal — two roles, one matrix

  2. Add roles as you identify new traceability needs

  3. Graduate to requirements-engineering or agile when your model stabilizes

  4. Customize via preset init when you need domain-specific adjustments

Troubleshooting

Items not appearing in matrices

Check that the item’s role matches a row or column in your configured matrices. Items with roles not referenced in any matrix still exist in the graph but won’t appear in matrix output.

Relationships not showing up

Verify the relation type is listed in coverageRelations for the relevant column. Only relations matching those types count as coverage.

"Relation not allowed" errors

Your configuration doesn’t permit that relation type between those roles. Check traceability.yml relations section. Add the missing type or use an allowed type.

"Unknown role" warnings

The item’s role attribute doesn’t match any role in your configuration. Either add the role to traceability.yml or correct the role attribute on the item.

Build completes but no traceability output

Verify enabled: true in your playbook config. Check that your .adoc files are in the Antora content catalog (have page family). Enable verbose Antora logging for more detail.