Skip to content

Follow Antora cross-file cross-references#81

Merged
bbatsov merged 1 commit into
masterfrom
antora-xref
Jun 5, 2026
Merged

Follow Antora cross-file cross-references#81
bbatsov merged 1 commit into
masterfrom
antora-xref

Conversation

@bbatsov

@bbatsov bbatsov commented Jun 5, 2026

Copy link
Copy Markdown
Owner

Phase 2 of the Antora/xref work, building on the section auto-ids from #80.

In a file inside an Antora component (a tree with an antora.yml), following an xref: that targets another page now actually goes there. xref:basics/install.adoc[], xref:other.adoc#a-section[], and module:page.adoc all resolve to the right file under the target module's pages/ directory, and the #fragment jumps to the matching section (reusing the auto-id resolver). It works from C-c C-o / M-. and a mouse click, pushes the xref marker stack so M-, returns, and stays out of the way outside Antora (a plain .adoc xref elsewhere falls through to the in-buffer handling).

Resolution is deliberately scoped to the current component - version@ and component:module: cross-component targets need Antora's site catalog, which we don't have, so they're left alone. I verified it against my real cider/doc and rubocop/docs layouts.

Still to come in later PRs: completion of xref page targets + #fragments, and project-wide xref-find-references; then paste-image.

  • The commits are consistent with our contribution guidelines
  • You've added tests (if possible) to cover your change(s)
  • All tests are passing (eldev test)
  • The new code is not generating bytecode or M-x checkdoc warnings
  • You've updated the changelog (if adding/changing user-visible functionality)
  • You've updated the readme (if adding/changing user-visible functionality)

In an Antora component (a tree with an antora.yml), following an xref to
another page - xref:topic/page.adoc[] or xref:other.adoc#a-section[],
optionally with a module: prefix - now opens the resolved page (under the
target module's pages/ directory) and jumps to the #fragment section,
reusing the section auto-id resolver. Works from C-c C-o / M-. and a
mouse click, pushes the xref marker stack so M-, returns, and stays out
of the way (falls through) outside Antora. Resolution is limited to the
current component; version@/cross-component targets are left alone.

Phase 2 of the Antora/xref work; completion of xref page targets and
project-wide references are still to come.
@bbatsov bbatsov merged commit 4547693 into master Jun 5, 2026
8 checks passed
@bbatsov bbatsov deleted the antora-xref branch June 5, 2026 11:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant