Getting Started

This tutorial walks you through setting up traceability from scratch. By the end, you’ll have a working Antora site with traceable items, relationships, and generated matrices.

If you already have an Antora site, skip to Step 2: Add the extension to your playbook.

Step 1: Set up an Antora site

If you don’t have an Antora site yet, create one:

mkdir my-docs && cd my-docs
npm init -y

Create a minimal Antora structure:

mkdir -p modules/ROOT/pages

Create an Antora playbook (antora-playbook.yml):

site:
  title: My Project Docs
  url: http://localhost:8080
content:
  sources:
    - url: ./
      branches: HEAD
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Create a home page (modules/ROOT/pages/index.adoc):

= Welcome

Hello world! This site uses traceability.

Create a navigation file (modules/ROOT/nav.adoc):

* xref:index.adoc[Home]

Create the component descriptor (modules/ROOT/antora.yml):

name: my-project
version: '1.0'

Verify the site builds:

npx antora antora-playbook.yml

Open public/index.html — you should see your home page.

Step 2: Add the extension to your playbook

Install the extension:

npm install antora-tracer --save-dev

Add it to your playbook (antora-playbook.yml):

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

The requirements-engineering preset defines five roles (requirement, design, implementation, test, document) and three matrices. You can explore other presets later — for now, stick with this one.

Build again to verify everything still works:

npx antora antora-playbook.yml

The build should complete without errors. The extension is active but won’t produce traceability output until you write some items.

Step 3: Write your first traceable items

Open modules/ROOT/pages/index.adoc and add three traceable items — a requirement, an implementation, and a test:

= Welcome
:traceability-links: true

[#REQ-001, item, role=requirement, title="REQ-001 — User authentication required"]
--
The system shall require authentication for all protected endpoints.
--

[#DES-001, item, role=design, title="DES-001 — JWT Authentication Design"]
--
JWT-based authentication with token refresh.

addresses:REQ-001[]
--

[#TEST-001, item, role=test, title="TEST-001 — Authentication integration tests"]
--
Unit and integration tests for the auth service.

validates:DES-001[]
verifies:REQ-001[]
--

Here’s what you wrote:

  • REQ-001 — a requirement item. The [#REQ-001, item, role=requirement] block macro tells the extension this is a traceable item of role requirement.

  • DES-001 — a design. It declares `` — a relationship pointing from this design to the requirement it addresses.

  • TEST-001 — a test. It references both the design it validates () and the requirement it verifies ().

The :traceability-links: attribute enables the traceability:outgoing[] and traceability:incoming[] macros, which display relationship lists in the rendered output.

Step 4: Build and see the results

Build the site again:

npx antora antora-playbook.yml

Open the built site and look at the Traceability section in the navigation. The requirements-to-tests matrix shows REQ-001 covered by TEST-001.

Open the site’s index.html — the item blocks render as styled sections in the page.

Step 5: Explore what you’ve built

Congratulations! You have a working traceability setup. Here’s what’s happening under the hood:

  • The extension found your three [item] blocks and registered them in the traceability graph

  • The inline relationships (, , ``) were validated against the preset’s configuration and stored

  • The requirements-to-tests matrix links REQ-001 to TEST-001 through the verifies relationship

Next Steps

Now that you’ve got the basics working, here’s where to go next:

To understand the concepts behind the extension, read: