How to Add Traceability Visualizations

The extension provides two visualization macros that render as diagrams in your HTML and PDF output. Both use Kroki (https://kroki.io) under the hood and require no local tooling.

Enable visualization macros

Add the :traceability-graph: document attribute to any page where you want visualizations:

= My Page
:traceability-graph: true

Without this attribute, the tracer:graph[] and tracer:graph-coverage[] placeholders are stripped from output.

Add a relationship graph

Place tracer:graph[] inside any item block:

[#REQ-001, item, role=requirement, title="User authentication"]
--
The system shall require authentication.

tracer:graph[]
--

This renders a 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.

By default, the graph shows one hop. For deeper graphs, pass a depth parameter:

tracer:graph[REQ-001, 2]

The 2 limits the graph to items within two hops.

Reference any item by ID — useful outside item blocks:

tracer:graph[REQ-001]

Add a coverage chart

Place tracer:graph-coverage[] inside any item block:

[#REQ-001, item, role=requirement]
--
tracer:graph-coverage[]
--

This renders a Vega-Lite bar chart showing per-relationship-type coverage for that item — which relations are present and which are missing.

For a global coverage chart (all roles), place it outside any item block:

= Dashboard
:traceability-graph: true

== Global Coverage

tracer:graph-coverage[]

Add a configuration graph

Place tracer:config-graph[] anywhere on a page to render the traceability configuration — the roles and the relations allowed between them — as a GraphViz diagram:

= Our Model
:traceability-graph: true

tracer:config-graph[]

Unlike tracer:graph[], which shows items, this macro shows the model: each configured role is a node, each declared relation is a labeled arrow. Only declared directions are drawn — reverse-derived edges are not rendered. Roles declared with no relations still appear as isolated nodes, which makes orphaned roles visible.

Enabling relationship link macros

For textual relationship lists (not diagrams), enable the link macros:

= My Page
:traceability-links: true
:traceability-style: table
:traceability-order: target-id

Then use tracer:outgoing[] and tracer:incoming[] inside item blocks. See Traceability Macros Reference for all options.

Local Kroki server

To use a local Kroki instance instead of the public kroki.io service, set krokiServerUrl in your playbook:

antora:
  extensions:
    - require: @antora-tracer/core/antora-extension
      krokiServerUrl: http://localhost:8000
      krokiImageFormat: png

Or set the environment variable: KROKI_SERVER_URL=http://localhost:8000. This works for air-gapped environments and avoids external network dependencies.

Generated overview page

In addition to the per-page macros, the extension generates a traceability overview into the output directory (traceability/overview.html by default), linked from the traceability dashboard index.html. The page reports managed/active/superseded totals, a per-role table, a superseded-items list with links, and a dangling-reference worklist (links whose target item no longer exists).

The overview is also registered as a site attachment at overviewTarget (default traceability/overview.html), so it is navigable via attachment$traceability/overview.html. Disable it with generateOverview: false in the extension config.

PDF compatibility

All visualization macros render identically in HTML and PDF — they generate standard AsciiDoc constructs (xrefs, images via Kroki URLs). The @antora/pdf-extension handles the image resolution.

Related