Choose a target version and inspect the native reference, expected sentence, and collected source identity. Missing and duplicate cases stay distinct; published URLs are not guessed.
Plan two small component versions
Use an original fictional handbook component with versions “1.0” and “2.0.” Each content source root has its own component descriptor and a ROOT module with index.adoc and setup.adoc in the pages directory.
| Source root label | Descriptor choices | page paths within the root |
|---|---|---|
| R1 | name: handbook; version: '1.0' | modules/ROOT/pages/index.adoc; modules/ROOT/pages/setup.adoc |
| R2 | name: handbook; version: '2.0' | modules/ROOT/pages/index.adoc; modules/ROOT/pages/setup.adoc |
R1 and R2 are source-root labels, not published URL segments. Quote the version strings in the YAML descriptors to preserve their intended text.
The authored setup content differs:
- Version 1.0: “Practice setup uses a paper checklist.”
- Version 2.0: “Practice setup uses a reviewed digital checklist.”
Record the actual installed Antora/runtime versions, playbook, content-source configuration, and UI configuration before any future build. The cited documentation identifies itself as Antora 3.2; that is a documentation reference, not a claim about your environment.
Make the five coordinates visible
Antora resource IDs identify source resources through version, component, module, family, and file coordinates. Their values come from the descriptor and source structure. The file coordinate is relative to its family directory. Resource ID coordinates
Write a native resource table:
| Version | Component | Module | Family | File |
|---|---|---|---|---|
| 1.0 | handbook | ROOT | page | index.adoc |
| 1.0 | handbook | ROOT | page | setup.adoc |
| 2.0 | handbook | ROOT | page | index.adoc |
| 2.0 | handbook | ROOT | page | setup.adoc |
The two setup records differ in their version coordinate. Their shared filename is not a collision.
The fully specified older setup ID is 1.0@handbook:ROOT:page$setup.adoc. Keep that exact native identifier distinct from a filesystem path and from the generated page URL.
Do not invent an output path such as a particular /handbook/1.0/setup.html route and treat it as the source identity. Record an actual generated URL after generation under the chosen configuration.
Reference the older page explicitly
In the version 2.0 index, use:
xref:1.0@handbook:ROOT:page$setup.adoc[Read version 1.0 setup]
Add a second, separately labeled reference for the current setup:
xref:2.0@handbook:ROOT:page$setup.adoc[Read version 2.0 setup]
Both originate from the 2.0 index. Their labels help the reader, but the version coordinate determines the intended target. A label saying “1.0” does not repair an ID that actually specifies 2.0.
Antora's xref documentation describes source-to-source references converted into links to published resources when it runs. The source ID is the input; the generated URL is an output to inspect. Xref macros and page links
The expected older target contains the paper-checklist sentence. The current target contains the reviewed-digital-checklist sentence. Record each reference and its expected target:
| Current source | Explicit target | Expected content | Actual generated link/content |
|---|---|---|---|
| 2.0 handbook ROOT index.adoc | 1.0 setup resource | Paper-checklist sentence | Not run |
| 2.0 handbook ROOT index.adoc | 2.0 setup resource | Reviewed-digital-checklist sentence | Not run |
An edited AsciiDoc snippet establishes what you asked for. It does not establish that the target was collected, the build completed, or the generated link works.
Change the current content without changing the old reference
Stage a revision that changes only the version 2.0 setup text. Retain the 1.0 resource, its paper-checklist sentence, and the explicit 1.0 xref.
The intended older target remains 1.0. A source update in 2.0 should not cause this example's explicitly versioned older reference to point at the newer source. The 2.0 target is the one whose expected content changes.
Recheck actual output after a future build. Keep previous inspection records associated with their source/build revision rather than relabeling them as fresh results.
Try the worked example
Inspect 1.0 for the paper-checklist target. Change only 2.0 text and inspect again: the old target stays fixed. Select missing or duplicate to expose the source problem before a native build. A resource ID is not a published URL.
This composes references and inspects authored records; it does not run Antora or prove generated-link behavior.
Recreate this example
Build one complete self-contained HTML page for this task: compose Antora references and inspect the original collected-resource scenarios.
Use these exact original practice data and worked expectations: The handbook has versions 1.0 and 2.0, a ROOT module, and page-family files index.adoc and setup.adoc. Old setup: Practice setup uses a paper checklist. Current setup: Practice setup uses a reviewed digital checklist. Full old ID: 1.0@handbook:ROOT:page$setup.adoc.
Implement the following useful local interactions: Target version input; Original,Changed2.0,Missing1.0,Duplicate 1.0 buttons and Inspect. Compose the xref and report expected sentence, missing source, or duplicate complete identity. Current-only revision leaves the old reference fixed. No native build. Preserve the supplied source text and distinguish an uncomputed state, a successful local result, and an invalid or incomplete input. Update output only from the current input snapshot. An input edit must retire stale feedback until the reader runs the relevant action again. Do not silently invent missing values or replace a failing case with a success.
Design the page as a compact source-and-result developer workbench with readable code, labeled inputs, and a separate explanation area. Put a compact task heading, actual sample data, the main result, and usable controls early enough to be useful on a narrow screen. Use readable text of at least 16px, generous paragraph spacing, strong contrast, native labels, accessible buttons, and visible keyboard focus. Stack long records at 360px and wrap code without page-level horizontal overflow.
Use type=button and explicit querySelector-based click handlers rather than relying on form submission. If Enter is useful, handle it only on the relevant input and ignore isComposing. Keep effects within this open page; no remote dependencies, network calls, persistence, fake downloads, or automated sending. This composes references and inspects authored records; it does not run Antora or prove generated-link behavior. Place worked explanations beside their data and identify teacher or synthetic examples clearly. Output only the complete HTML document, with inline styles and script and LF line endings.
Review the versioned resource and xref builder in NOS
Put the explicit reference in your source and inspect its actual target after a native build. Use the resource explanation in NOS to review which checklist each reference should reach, and revise eligible static checklist descriptions in visual editing mode.