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.
Header role classes are not limited to tracer: any class in the header is accepted, so [.tracer.status-draft#REQ-001, item, …] is a valid item declaration.
Status class
An item that declares a status gets an additional CSS class on its rendered block, derived from the status value:
[#REQ-001, item, role=requirement, status="In Review", title="Title"]
--
Item content.
--Asciidoctor renders it as:
<div id="REQ-001" class="openblock requirement tracer-status-in-review">The class name is the status value lowercased, with each run of non-alphanumeric characters replaced by a single -, prefixed with tracer-status-:
status value |
Emitted class |
|---|---|
|
|
|
|
|
|
|
|
omitted, empty, or only punctuation |
none |
The class is emitted on every item that declares a status and is never configurable.
The extension itself renders no icon, badge, or color for it: all decoration comes from a stylesheet.
The tracer- namespace keeps it distinct from the matrix’s status-done, status-partial, and status-missing coverage classes, which describe matrix coverage rather than item status.
The conemso UI theme ships a default glyph for five common statuses, so those render with no project CSS at all:
status value |
Glyph | Class |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The theme appends the glyph to the title with a ::after rule:
.doc .openblock.tracer-status-approved > .title::after { content: "\2713"; }Decorate other statuses, or override the theme, in the site’s own stylesheet.
The class is on the item block, not the title, so target .title from it:
.tracer-status-in-review > .title::after { content: "\21BB"; color: var(--warning-color); }Glyphs need a font that carries them: the theme’s Roboto subsets do not, so a custom rule should name a symbol-capable family, or the browser may substitute one that renders an empty box.
.tracer-status-in-review > .title::after {
content: "\21BB";
font-family: "DejaVu Sans", "Segoe UI Symbol", "Apple Symbols", sans-serif;
}Scope rules to selected pages by scoping them to a page role.
A page header :page-role: show-status-glyphs renders as a body class, so the decoration applies only where a page asks for it:
.show-status-glyphs .tracer-status-draft > .title::after { content: "\270E"; }Status classes are an HTML and CSS feature. They have no effect in the PDF and DOCX builds, which do not consume CSS.
Attributes
| Attribute | Required | Description |
|---|---|---|
|
Yes |
Unique identifier. Must be unique across all items in the graph. Recommended format: |
|
Yes |
Must match a role defined in your configuration. Case-insensitive. Unknown roles generate a warning but the item is still stored |
|
No |
Display title. Defaults to the |
|
No |
Free-form status: |
|
No |
Free-form priority: |
|
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-IDmust match theidof 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[]).
Validation
The extension validates items and relationships at processing time:
Role validation
-
Role exists: If
role=widgetandwidgetisn’t in the config, warning:Unknown role "widget". Known roles: requirement, design, test.
Relation validation
-
Relation allowed: Checks
source role → target roleagainst therelationsmap. 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
-
How to write traceable items — practical guide
-
Traceability Macros Reference — rendering macros
-
Configuration Reference — role and relation configuration