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 traceability:graph[] and `` placeholders are stripped from output.

Add a relationship graph

Place traceability:graph[] inside any item block:

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


--

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:

   (1)
1 Shows the item and items within two hops

Reference any item by ID — useful outside item blocks:

Add a coverage chart

Place `` inside any item block:

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

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

Add a configuration graph

Place `` 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

traceability:config-graph[]

Unlike traceability: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 traceability:outgoing[] and traceability: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/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.

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