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="ARC-005 — Zero operational overhead"]
\--
Description of how zero operational overhead is achieved...
\--

Include it in a page:

// architecture.adoc
= Architecture
== 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.



.Addresses
* xref:requirements:index.adoc#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.



.Addresses
* xref:requirements:index.adoc#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.



.Addresses
* xref:requirements:index.adoc#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.



.Addresses
* xref:requirements:index.adoc#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.



.Addresses
* xref:requirements:index.adoc#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.



.Addresses
* xref:requirements:index.adoc#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`.



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

--

The extension processes partials during graph population on equal footing with page files.

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="ARC-002 — 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