Traceability Macros Reference

Namespace alias

Every macro on this page is also available under the shorter tracer: prefix. The two namespaces are equivalent and may be used side-by-side as a migration path:

tracer:outgoing[]
tracer:incoming[]
tracer:links[]
tracer:graph[]
tracer:graph-coverage[]

tracer: remains fully supported and is not deprecated. New content may use either prefix.

Relationship Link Macros

When :traceability-links: resolves to true, every item automatically renders its outgoing and incoming relationship lists using the configured display options. An explicit tracer:outgoing[], tracer:incoming[], or tracer:links[] macro overrides automatic rendering for that item and controls its direction and placement.

A relationship whose target item lives only in an excluded component (the excludeComponents option in Configuration) stays pending and is reported with a "Target item not found" warning. It renders no link and creates no stub item.

tracer:outgoing[]

Lists items that this item points to (outgoing relationships). Place inside an item block:

[#REQ-001, item, role=requirement]
--
Requirement description...

tracer:outgoing[]
--

tracer:incoming[]

Lists items that point to this item (incoming relationships). Uses the reverse relation’s display label (e.g., an incoming addresses edge displays as "Addressed by"):

tracer:incoming[]

tracer:links[]

Shows both outgoing and incoming relationships in one call:

tracer:links[]

Enabling

Enable automatic relationship rendering for every item on a page with the document attribute:

= Architecture
:traceability-links: true

For a component-wide default, set the attribute in the component descriptor’s antora.yml:

asciidoc:
  attributes:
    traceability-links: true

or in the playbook:

asciidoc:
  attributes:
    traceability-links: true

A page-level :traceability-links: header overrides the component or playbook setting for items authored in that page. Items defined in partials use their own component’s setting; the including page’s header does not override it, and partials need no local setting. When the resolved setting is absent or false, explicit relationship rendering macros are stripped from output and automatic links are not added.

Display options

Attribute Values Effect

:traceability-links:

true

Renders automatic outgoing and incoming relationship lists and enables explicit rendering macros

:traceability-style:

list (default), table, inline

Display format: bulleted list, AsciiDoc table, or comma-separated inline

:traceability-order:

target-id (default), target-title, relation-type

Sort order

:traceability-collapsible:

true

In list style, wrap all relation-type groups in one Links disclosure, with headings inside (HTML only).

Superseded items

When an item is superseded, its block renders with a (superseded by <successor>) marker. Set renderSuperseded: false in the extension config to omit superseded item blocks and their supersedes links from rendered output. This is display-only — the graph and matrices are unaffected.

PDF and DOCX compatibility

The macros generate standard AsciiDoc constructs (xrefs, lists, tables) — compatible with HTML, PDF, and DOCX backends. The @antora/pdf-extension renders them identically in PDF; the @antora/assembler with adoc-to-docx renders them in DOCX.

Visualization Macros

These macros render diagrams. They are gated by the :traceability-graph: document attribute.

tracer:graph[]

Renders a relationship graph diagram.

= Dashboard
:traceability-graph: true

[#REQ-001, item, role=requirement]
\--
Requirement description...

tracer:graph[]
\--

Renders a Kroki-generated GraphViz DOT diagram showing the item and all directly related items (both outgoing and incoming). Nodes are colored by role; edges are labeled with relation types.

Explicit target

Reference any item by passing an explicit ID:

tracer:graph[REQ-001]

Depth parameter

Pass a depth to control how many hops are shown (default 1):

tracer:graph[REQ-001, 2]

===

Renders a coverage bar chart.

Inside an item — per-relationship-type coverage:

tracer:graph-coverage[]

Outside any item — global role-based coverage:

= Dashboard
:traceability-graph: true

tracer:graph-coverage[]

Renders a Kroki-generated Vega-Lite bar chart. Both macros auto-scale and have no additional attributes beyond :traceability-graph:.

Enabling

= Dashboard
:traceability-graph: true

Kroki configuration

Both macros generate URLs pointing to the configured Kroki server. The image format (SVG/PNG) is controlled by krokiImageFormat, the server URL by krokiServerUrl.

Default: kroki.io (SVG format)
antora:
  extensions:
    - require: @antora-tracer/core/antora-extension
      # defaults: krokiServerUrl: https://kroki.io, krokiImageFormat: svg
Local Kroki server (PNG for PDF)
antora:
  extensions:
    - require: @antora-tracer/core/antora-extension
      krokiServerUrl: http://localhost:8000
      krokiImageFormat: png

You can also set KROKI_SERVER_URL and KROKI_IMAGE_FORMAT environment variables, which take precedence over extension config.

Related