Item Macro Reference

Syntax

[#ID, item, role=<role>, title="Title", status="draft", priority="high"]
--
Item content. Can span multiple paragraphs.

Inline relationships go anywhere inside the block:

<relation-type>:TARGET-ID[]
<relation-type>:TARGET-ID[]
--

Both -- (open block) and ==== (example block) are valid delimiters for the item block. -- renders the item inline with no frame; ==== renders it boxed with a shaded background. The choice is presentational — the parser treats them identically. This documentation uses --.

Item content boundaries

The parser stores only text between the delimiters as item content. Section headings such as === Rationale inside the block render as literal text, not as AsciiDoc sections. A heading outside the block renders normally, but its text is not part of the graph item or its exports. Keep item prose and relationship macros inside the block so they belong to the item. Keep display macros such as tracer:links[] inside the block; the extension expands them only there.

To add a CSS class to the rendered item block, prefix the ID with the .tracer role:

[.tracer#REQ-001, item, role=requirement, title="Title"]
--
Item content.
--

This form is equivalent to [#REQ-001, item, …​] for parsing and traceability. Asciidoctor renders it with id="REQ-001" and the tracer CSS class, in addition to the configured item role class. For example, target the title in the HTML UI stylesheet with .openblock.tracer > .title. The .tracer role syntax is optional and does not change the role attribute used by the traceability configuration.

Attributes

Attribute Required Description

id

Yes

Unique identifier. Must be unique across all items in the graph. Recommended format: ROLE-NNN (e.g., REQ-001, STORY-042)

role

Yes

Must match a role defined in your configuration. Case-insensitive. Unknown roles generate a warning but the item is still stored

title

No

Display title. Defaults to the id if omitted. Used in matrix cells, macro output, and Neo4j export

status

No

Free-form status: draft, reviewed, approved, implemented, deprecated

priority

No

Free-form priority: high, medium, low

tags

No

Comma-separated tags stored as structured item metadata. See the tag value syntax below.

Any additional attributes are stored in the item’s attributes map and exported to Neo4j as node properties. Link display policies can match additional item attributes by exact string name and value.

Quote the value when it contains commas, for example tags="security, privacy". Surrounding whitespace is trimmed and empty entries are ignored. If omitted, the item’s tag list is empty.

Inline Relationship Macros

A relationship is expressed as <relation-type>:TARGET-ID[] anywhere inside the item block:

[#DES-001, item, role=design]
--
Auth Service

addresses:REQ-001[]
depends_on:DES-002[]

--

Syntax rules

  • Multiple targets per type: addresses:REQ-001,REQ-002,REQ-003[]

  • Multiple types per item: write each on its own line

  • The TARGET-ID must match the id of another item in the graph

  • Missing targets generate a warning, not an error

As header attributes

A relationship can also be declared in the item header using its configured relation type as an attribute:

[#DES-001, item, role=design, addresses="REQ-001, REQ-002"]
--
Auth Service
--

The value accepts target IDs separated by commas or whitespace. Quote the value when it contains commas so the header parser treats it as a single attribute.

Only names configured as relation types (primary or reverse) become relationships; other attributes stay item metadata and are exported to Neo4j as node properties. Header attributes follow the same canonicalization, validation, rendering, and duplicate handling as inline macros.

Visibility

Inline relationship macros are always invisible in rendered output. They are pure data markers stored in the traceability graph. To display relationships in documentation, use:

  • tracer:outgoing[] — lists items this item points to

  • tracer:incoming[] — lists items that point to this item

  • tracer:links[] — shows both directions

Each display macro also accepts the tracer: prefix as an alias (e.g. tracer:links[]).

See Traceability Macros Reference.

Validation

The extension validates items and relationships at processing time:

Role validation

  • Role exists: If role=widget and widget isn’t in the config, warning: Unknown role "widget". Known roles: requirement, design, test.

Relation validation

  • Relation allowed: Checks source role → target role against the relations map. Disallowed relations generate errors with the allowed types listed.

  • Target exists: Missing targets generate: Target item not found: MISSING-001.

Graph validation

  • Circular references: DFS-based cycle detection. Reports cycles with the full path: Circular reference detected: REQ-001 → REQ-002 → REQ-001.

  • Self-references: An item referencing itself is also detected and reported as circular.

Warnings don’t block processing; errors do. Unknown roles generate warnings (graceful degradation). Invalid relations generate errors.

Related