A broken link announces itself. A link to the wrong release may not. Imagine a version 1.0 manual that links to timeout rules in a separate reference component. The link works, the build is clean and the reader sees a clear explanation. Unfortunately, it describes version 2.0, where the illustrative default changed from 30 to 60 seconds.
Understanding Antora xrefs helps with both problems: the visible “target of xref not found” message and the quieter mistake of reaching the wrong content. The skill is to identify the source page you mean, account for the current context and verify the generated destination. Guessing a published URL skips the part that makes Antora references useful.
1. Understand what an xref identifies
An Antora page has a resource ID based on its component version, module and location within the pages directory. It is independent of the eventual published URL. Antora uses that ID to look up the source and generate the link. The official Resources and Resource IDs guide explains the distinction.
xref:1.0@manual:ROOT:setup/install.adoc[Install the service]
└┬┘ └─┬──┘ └─┬┘ └────────┬───────┘
│ │ │ └─ page within pages/
│ │ └─ module
│ └─ component
└─ version
The component name comes from name in the target antora.yml. Its display title is a different value. The module comes from the directory directly beneath modules. ROOT is the special default module name; it is still a module. The file coordinate includes setup because the page is beneath pages/setup, and ends in .adoc because it identifies a source page.
The brackets contain the text readers click. They are not part of the lookup address. You can change “Install the service” without moving the target. For the coordinate syntax and permitted abbreviations, consult Resource ID Coordinates.
2. Use one project to test every kind of link
Download the navigation and cross-reference lab. It pins Antora 3.2.1 and includes manual 1.0 and 2.0, reference 1.0 and 2.0, two modules and a page with an explicit section anchor. The sample product instructions and timeout values are fictional.
You need Node.js 22.13 or later, npm, Git and internet access for installation and the first UI download. Extract into a new folder and run these commands from the project root:
git init
npm ci
npm run build
Open build/site/index.html. The start page is deliberately manual 1.0. Read its two timeout links before changing anything: the pinned link opens reference 1.0, and the link without a version opens reference 2.0. The generated output gives you a baseline against which to judge each experiment.
3. Abbreviate coordinates only when the context is clear
From manual 1.0’s ROOT overview, these references express different relationships:
| Target | Reference from the ROOT overview |
|---|---|
| Same module and version | xref:setup/install.adoc[Install] |
| Another module, same component version | xref:admin:backup.adoc[Back up the service] |
| A specific version of another component | xref:1.0@reference::timeouts.adoc[Version 1.0 timeouts] |
| Latest version of another component | xref:reference::timeouts.adoc[Latest timeout rules] |
| Another version of the manual | xref:2.0@manual::index.adoc[Version 2.0 overview] |
The empty module between the two colons selects ROOT in these component-qualified references. From admin/pages/backup.adoc, returning to the overview requires ROOT:index.adoc. Without the module coordinate, index.adoc would be sought in admin, where this lab has no such page.
For ordinary same-module references, express the file path from the pages directory: setup/install.adoc. It is not modules/ROOT/pages/setup/install.adoc and it is not the output path manual/1.0/setup/install.html. Keeping the source address separate from both filesystem scaffolding and published URLs removes two common sources of errors.
There is also a ./ shorthand for a target in the current page’s own subdirectory. Use it deliberately rather than assuming every bare filename is relative to the current file. Antora’s Create Page Links guide illustrates the difference. Our lab uses pages-relative paths so the intended address stays visible.
4. Diagnose “target of xref not found” from the target backwards
This message means the referenced page resource could not be resolved in the assembled content catalog. It does not, by itself, prove that a file was deleted. The file may exist on disk but be outside the selected content, belong to another module or have a different component identity.
First note the source page or navigation file named in the build message. Then locate the intended target and read its enclosing antora.yml. Write down its name, version, module and pages-relative path. Construct a fully qualified reference from those facts before deciding whether an abbreviation is appropriate.
| Broken example or assumption | What to check or change |
|---|---|
xref:setup/install.html[] |
Use setup/install.adoc: the source file, not generated HTML. |
xref:pages/setup/install.adoc[] |
Remove pages/: that directory is already the root of the page coordinate. |
xref:backup.adoc[] from ROOT
|
Use admin:backup.adoc because the target belongs to admin. |
xref:1.0@service-reference::timeouts.adoc[] |
Read the target descriptor. This lab’s name is reference, regardless of its title. |
| A correct ID for a version omitted from the playbook | Select that content source/reference and start path, then rebuild. |
| A reference that still names the old file after a rename | Update each affected reference, including navigation and section links. |
Also compare spelling and letter case exactly. A local filesystem can conceal a capitalization mistake that another environment exposes. Establish one filename convention, review the committed filenames and use that spelling consistently. Renaming files at random until a build passes makes the actual relationship harder to understand.
If the coordinates look right, inspect what the playbook actually collects. A branch, tag or start path can exclude the intended resource. The repository is the potential source; the selected content is what the current build can resolve. Antora’s content-source configuration is the next useful reference.
5. Treat a file rename as a small dependency change
In the lab, rename setup/install.adoc to setup/deploy.adoc without changing anything else. Rebuild. The old resource is referenced from the overview, the menu and the backup page’s verification link. Fixing only the first message leaves the other reading paths broken.
Page: ROOT/pages/setup/install.adoc → setup/deploy.adoc
Overview: xref:setup/deploy.adoc[]
Menu: ** xref:setup/deploy.adoc[]
Backup: xref:ROOT:setup/deploy.adoc#verify-installation[installation verification]
Search the selected project sources for setup/install.adoc, review each occurrence in context and update the ones that target the renamed page. A textual match is a useful lead, not permission to replace every occurrence blindly: another version might intentionally retain the old filename, or an example may be discussing it.
Rebuild and follow all three routes. Then restore the original filename and references before the next exercise. In a production site, a separate question remains: do people already use the old published URL? Repairing source xrefs does not automatically preserve external bookmarks. Antora supports page aliases for appropriate migrations.
For a deliberate move from setup/install.adoc to setup/deploy.adoc, the renamed page can claim its previous resource ID with this header. The alias lets existing source references resolve and creates redirect information for the former page URL. It is an alternative to requiring every old reference to change immediately; review whether the new page really serves the old page’s purpose.
= Install and verify the service
:page-aliases: setup/install.adoc
:navtitle: Install
:reftext: installation guide
Check the generated redirect using your actual hosting setup. A page alias is useful for a specific page move; retiring a whole component or release needs a separate redirect plan. It also does not repair a removed section anchor inside the destination page.
6. Decide whether a cross-component link should follow a release
The lab’s overview contains these two links:
xref:1.0@reference::timeouts.adoc[Version 1.0 timeout rules]
xref:reference::timeouts.adoc[Latest timeout rules]
Both resolve successfully. The first deliberately selects reference 1.0. The second selects the latest reference version, which is 2.0 in this lab. A clean build cannot tell you whether the unpinned choice matches the compatibility needs of manual 1.0.
“Latest” is determined by Antora’s component version ordering and prerelease rules, rather than by which source file you edited most recently. Review How Component Versions are Sorted before relying on custom version labels.
Choose a pinned version when the destination explains release-specific behavior, such as supported options, configuration defaults or migration steps. A latest-version link can suit a deliberately maintained overview or support policy. State that intention in review. The important question is what happens when someone publishes reference 3.0 while manual 1.0 remains online.
For links within the same component version, a short module/file reference normally preserves the current version context. Cross-component references need an explicit compatibility decision. Give reviewers a small rule they can apply, such as “release procedures pin external reference versions; evergreen overview links may follow latest.”
7. Check section links separately from page links
A section reference adds a fragment after the page coordinate. The installation page gives its verification section an explicit ID, which is useful when headings may be edited later:
[#verify-installation]
== Verify the installation
Confirm that the service starts.
xref:ROOT:setup/install.adoc#verify-installation[installation verification]
A stable, explicit ID lets you improve the heading without relying on a new automatically generated section ID. It still needs maintenance: deleting or changing the explicit ID can break incoming section links. Use descriptive IDs that make sense outside the immediate paragraph.
In the lab’s backup page, change only the fragment to #not-there. Build again and follow the link. A successfully resolved page does not establish that the target section exists. In Antora 3.2.1 this exercise can produce a clean build while leaving a link that fails to reach the intended section. Inspect the heading or use a suitable fragment-aware output check.
Supply meaningful link text for section references. Empty brackets do not provide the same automatic title behavior as an ordinary whole-page link. The page link-text rules explain the cases. “Verify the installation” also tells a reader more than “click here.”
8. Make build errors affect the result of the command
Seeing generated HTML is not sufficient evidence that a build was clean. Antora can log an unresolved xref and still write output. Its default failure threshold is fatal. The lab deliberately lowers that threshold:
runtime:
log:
failure_level: error
With Antora 3.2.1, an error meeting this threshold makes the command exit with status 2. This setting affects the exit status; it does not promise to stop all processing or prevent output files from being written. See Log Failure Level. A publishing process must actually respect a failed command before deploying that output.
Keep three checks distinct: resource resolution asks whether Antora found the page; output checks ask whether links and fragments work in the generated site; editorial review asks whether those destinations explain the right thing for the reader’s version. Passing one does not replace the other two.
9. Use a repeatable reference review
For a page move or rename, identify the target component version, inspect the affected links, change the page and references, then check the generated destinations. A reference that resolves to the wrong release is still wrong for the reader.
Before closing a reference-related change, answer four questions:
- Does the source resource ID resolve?
- Is it the intended version?
- Does the target section exist?
- Does the link text accurately describe the destination?
Those questions turn an opaque build message into a repair process a technical writer can repeat.
Original article: Antora Xrefs Explained on AsciiLore.
This article was prepared with AI assistance. The accompanying examples were tested with Antora 3.2.1.
Top comments (0)