How to Use Partial Files with Items

You can define [item] blocks in AsciiDoc partials — files in a partials/ directory included into pages via include::partial$…​[]. This is useful for keeping architectural decisions or shared requirements in standalone files.

Define items in a partial

Create a partial file in modules/ROOT/partials/:

// partials/04-solution-strategy.adoc
== Solution Strategy

[#ARC-005, item, role=design, title="Zero operational overhead"]
\--
Description of how zero operational overhead is achieved...
\--

Include it in a page:

// architecture.adoc
= Architecture
:traceability-link-policy: l2-to-l3-addressing
== Solution Strategy

The following items describe how individual quality goals are addressed by
architecture decisions documented in the xref:explanation/adr/index.adoc[ADRs] and quality
acceptance criteria in the xref:explanation/quality/index.adoc[Quality Attributes].

[#ARC-005, item, role=design, title="ARC-005 — Zero operational overhead"]
--
xref:explanation/quality/zero-operational-overhead.adoc[Zero operational overhead] is
achieved through an in-memory graph (xref:explanation/adr/0003-in-memory-graph.adoc[ADR-003])
no external services, and a minimal dependency tree
(xref:explanation/adr/0004-zero-framework.adoc[ADR-004]).
Optional features like Neo4j export degrade gracefully without warnings.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-055[QA-055 — Zero operational overhead]
====


--

[#ARC-006, item, role=design, title="ARC-006 — Configurable without code changes"]
--
xref:explanation/quality/configurable-without-code.adoc[Configurable without code changes]
is achieved through YAML-based roles, relations, and matrices via
`ConfigLoader`.
Built-in presets can be extended or overridden.
Items with unknown roles generate warnings, not errors — enabling
incremental domain model adoption.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-056[QA-056 — Configurable without code changes]
====


--

[#ARC-007, item, role=design, title="ARC-007 — Fail-fast with clear diagnostics"]
--
xref:explanation/quality/fail-fast-diagnostics.adoc[Fail-fast with clear diagnostics]
is achieved through role-based relation validation at processing time
and post-hoc re-validation for cross-file references.
Error messages
include file, line, item IDs with roles, and allowed alternatives.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-057[QA-057 — Fail-fast with clear diagnostics]
====


--

[#ARC-008, item, role=design, title="ARC-008 — No side effects on source files"]
--
xref:explanation/quality/no-side-effects.adoc[No side effects on source files]
is achieved by performing all content transformations on in-memory
buffers.
Source `.adoc` files are never written to.
Processing is idempotent.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-058[QA-058 — No side effects on source files]
====


--

[#ARC-009, item, role=design, title="ARC-009 — Testability by design"]
--
xref:explanation/quality/testability-by-design.adoc[Testability by design]
is achieved through constructor-based dependency injection
isolated test files per module, and graph state exposed for test access.
The regex-based parser (xref:explanation/adr/0002-regex-parser-over-ast.adoc[ADR-002])
is decoupled from Asciidoctor's API.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-059[QA-059 — Testability by design]
====



--

[#ARC-010, item, role=design, title="ARC-010 — Future-proofness"]
--
Future-proofness is achieved through ESM with `"type": "module"`
(xref:explanation/adr/0001-esm-over-cjs.adoc[ADR-001]), TypeScript strict mode
and a Node.js 20+ baseline (xref:explanation/adr/0005-typescript-strict-node20.adoc[ADR-005]).
The zero-framework policy avoids dependency on libraries with short upgrade cycles.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-061[QA-061 — Platform stability and longevity]
====


--

[#ARC-011, item, role=design, title="ARC-011 — Performance through indexing"]
--
Performance is achieved through forward, reverse, and inverse
relationship indexes (O(1) lookup), result caching with invalidation
on mutation, and BFS path finding with configurable `maxDepth`.



[%collapsible]
.Links
====

.Addresses
* xref:requirements:index#QA-062[QA-062 — Query and indexing performance]
====


--

The extension processes partials during graph population and relationship rendering using their component’s AsciiDoc attributes.

Automatic relationship rendering for items in a partial follows the partial component’s traceability-links attribute. No attribute is needed in the partial, and the including page’s header does not override the component setting. Link visibility has a separate scope: the including page’s resolved :traceability-link-policy: overrides the partial component’s policy for all included items. If no policy resolves in the page context, the partial component’s policy applies. This filters output only and leaves the relationship graph unchanged. Define the selected policy under linkDisplayPolicies in traceability.yml; see Configuration Reference.

Where links point

  • Page items link to the rendered HTML page: architecture.html#ARC-001

  • Partial items link to the source file in your content repository: https://github.com/…​/blob/main/partials/04-solution-strategy.adoc#ARC-005

Partials don’t produce their own HTML pages — Antora only renders pages. The extension uses Antora’s content source URL to build a view link into your repository.

Pattern: Page-defines-item, partial-for-body

When you want matrix links to point to rendered HTML (not the repo), keep the [item] block in a page file and use a partial only for body text:

// architecture.adoc

[#ARC-002, item, role=design, title="Component-level architecture"]
\--
include::partial$building-block-overview.adoc[]
\--
// partials/building-block-overview.adoc
The system is organized into the following components...
// Plain AsciiDoc — no [item] blocks

The item’s ID and relationships stay in the page file; the partial provides the body prose.

Which pattern to choose?

Scenario Pattern Why

Self-contained design discussion

Partial-defines-item

The partial is the authoritative source

Long component descriptions with traceability links

Page-defines-item, partial-for-body

Relationships stay visible in the page

Content reused across multiple pages

Page-defines-item, partial-for-body

Avoids duplicate IDs

Do not cross-reference partial items

Do not use xref:partial$…​ to reference items defined in partials. Use inline relationship macros instead, or a plain link: URL. Partials don’t produce HTML pages, so cross-references won’t resolve.

Troubleshooting

Items defined in partials missing from matrices: Verify the partial is in a partials/ directory within your Antora module. The extension processes family: partial automatically.

"target of xref not found": You’re trying to xref an item in a partial. Use inline relationship macros instead.

Related