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

These macros display relationship lists as formatted text. They are gated by the :traceability-links: document attribute.

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

Opt-in per page via document attribute:

= Architecture
:traceability-links: true

Or enable it globally by setting the attribute in the component descriptor’s antora.yml:

asciidoc:
  attributes:
    traceability-links: true

or in the playbook:

asciidoc:
  attributes:
    traceability-links: true

A per-page :traceability-links: header overrides the global setting.

Without the attribute, the macro text is stripped from output.

Display options

Attribute Values Effect

:traceability-links:

true

Enables the 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

Wrap output in collapsible <details> sections by relation type (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