Traceability Macros Reference

Relationship Link Macros

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

traceability:outgoing[]

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

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

traceability:outgoing[]

traceability: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"):

traceability:incoming[]

traceability:links[]

Shows both outgoing and incoming relationships in one call:

traceability:links[]

Enabling

Opt-in per page via document attribute:

= Architecture
:traceability-links: true

Without this 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)

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.

traceability:graph[]

Renders a relationship graph diagram.

= Dashboard
:traceability-graph: true

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

traceability: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:

Depth parameter

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

===

Renders a coverage bar chart.

Inside an item — per-relationship-type coverage:

Outside any item — global role-based coverage:

= Dashboard
:traceability-graph: true

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/antora-extension
      # defaults: krokiServerUrl: https://kroki.io, krokiImageFormat: svg
Local Kroki server (PNG for PDF)
antora:
  extensions:
    - require: antora-tracer/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