Broken links in breadcrumbs outside nav

[alandefreitas]

When pages are not in the nav.adoc, the Antora UI creates broken links in the breadcrumbs and page titles.

To replicate the issue include the following files in any project:

// modules/ROOT/nav.adoc
# ...
* xref:root-link.adoc[]
# ...

// modules/ROOT/pages/root-link.adoc
= Root link

xref:test:A.adoc[A]

// modules/test/pages/A.adoc
= A with a link to xref:B/B.adoc[B]

Link to xref:B/B.adoc[B]

// modules/test/pages/B/B.adoc
= B with a link to xref:A.adoc[A]

Link to xref:A.adoc[A]

The links in B will be broken in the breadcrumbs and the title, but not in the content of the B.adoc file.

[alandefreitas]

I've been investigating this issue. The problem is that Asciidoc and Antora have different behaviors for xrefs and, to make it worse, Antora uses the Asciidoc behavior for the title.

So Antora doesn't support relative paths, and all xrefs must be relative to the module pages. So xref:a/b.adoc renders as <module>/a/b.html.

On the other hand, Asciidoc supports relative paths and paths are rendered relative to the current page. So xref:a/b.adoc renders as <current page>/a/b.html.

These two things are not the same. So unless all pages are in the root module pages, we would have broken links either in Antora or Asciidoc. To make things worse, Antora uses the default Asciidoc behavior for the title, so

= xref:a/b.adoc

xref:a/b.adoc

would render as <current page>/a/b.html and then <module>/a/b.html for the exact same xref. And breadcrumbs would also have the broken link when it's not in nav.adoc because it just replicates the title.

The solution I found was to set the relfileprefix attribute.

The attribute prepends all xrefs with some prefix (like "../", etc). This fixes the problem with Asciidoc. The solution isn't supposed to be needed in Antora, but it also fixes the problem with titles and breadcrumbs.

So this issue becomes less urgent now that we don't have broken links for the boost documentation 1.87. It's still worth checking the rules the Antora UI uses to render these breadcrumbs and title and see if there's something we can do about it in the general case.

I think most people don't ever have this issue because they don't include links in the title, but MrDocs does.

[rbbeeston]

Thanks for the info, I think I'll move this to a priority 3 for now, as it shouldn't affect the release, or break anything in the near term related to getting the launch done.

[julioest]

Adding the zulip link for reference: https://antora.zulipchat.com/#narrow/channel/282400-users/topic/Relative.20xrefs