relfileprefix on multipage pages blocks doc-comment links to non-reference pages

[jll63]

Summary

:relfileprefix:, set by adoc/layouts/wrapper.adoc.hbs on every multipage symbol page, makes it impossible for a doc comment on a nested symbol to link to a page outside the generated reference. Under Antora that means a reference page cannot link back to a hand-written guide page, so the cross-reference between narrative docs and reference is one-directional.

Background

A doc comment can reach a non-symbol page by giving a markdown link an Antora resource ID as its target — markup/a.adoc.hbs emits a scheme-ful href verbatim, so the ID survives:

/// @see [Shared Libraries](xref:ROOT:shared_libraries.adoc)
#define MY_MACRO(x) /* ... */

→ xref:ROOT:shared_libraries.adoc[Shared Libraries]

This works on pages at the output root. It fails on every nested page.

Cause

wrapper.adoc.hbs emits

:relfileprefix: {{{ page.relfileprefix }}}

with the comment "As Antora does not support relative links to pages in parent directories, the relfileprefix attribute is set to make all links relative to the root directory."

Asciidoctor folds relfileprefix into the path attribute of an inter-document xref, and Antora's converter uses exactly that attribute as the resource ID to resolve (asciidoc-loader/lib/converter/html5.js: let refSpec = node.getAttribute('path')). So a module-qualified ID is corrupted:

xref:ROOT:error_handling.adoc  ->  ../../ROOT:error_handling.adoc  ->  target of xref not found

A leading ../../ can never be part of a valid resource ID, so no spelling of the link survives.

Why the attribute cannot simply be dropped

Clearing it (relfileprefix: '', locked from the Antora playbook) does fix those links, and MrDocs' own body xrefs keep resolving — Antora resolves xref:boost/openmethod/foo.adoc family-root-relative, no prefix needed. But it breaks the document title:

= xref:boost.adoc[boost]::xref:boost/openmethod.adoc[openmethod]::ambiguous_call

Title xrefs are not processed by Antora's converter — they are converted by plain Asciidoctor, which does need relfileprefix to produce a usable relative path. On a real project (Boost.OpenMethod, ~200 nested reference pages) I measured:

configuration	broken internal links
relfileprefix as MrDocs sets it	the guide links only
relfileprefix cleared	~1250 (h1 + breadcrumb on every nested page)

So the attribute is load-bearing for exactly one thing: the title.

Suggested fix

Have symbol/qualified-name-title build its parent links with page.relfileprefix applied to the href directly, and stop emitting the document attribute. The title then works under plain Asciidoctor as it does today, Antora resolves body xrefs on its own, and a module-qualified resource ID in a doc comment survives — making reference → guide links possible from any page.

A lighter variant, if inlining the prefix in the title is awkward: render the parent names as plain text and drop the attribute. That loses the clickable breadcrumb.

Environment

MrDocs 0.8.0+e37b111 and current develop, generate: adoc, multipage: true, consumed by Antora 3.1.14 via @cppalliance/antora-cpp-reference-extension.

[alandefreitas]

So the attribute is load-bearing for exactly one thing: the title.

I don't believe this is correct. Are there \refs in Boost.OpenMethod? Unless things have changed since the last time we discussed this in the Antora Zulip, Antora doesn't allow relative links involving parents (links with ".."). Thus, we can't use the same strategy we use for HTML pages and have to use absolute links from the module's root, which also require :relfileprefix: to work reliably. In fact, this is the reason we need a module just for reference documentation at all, because if we had relative links we could inject the documentation anywhere even in an existing module. I think the conclusion "So the attribute is load-bearing for exactly one thing: the title." is just a circumstantial conclusion for Boost.OpenMethod rather than an exhaustive description of the consequences.

[jll63]

I think the conclusion "So the attribute is load-bearing for exactly one thing: the title." is just a circumstantial conclusion for Boost.OpenMethod rather than an exhaustive description of the consequences.

Claude authored and posted this issue without asking confirmation. Feel free to close if it's complete garbage.

[jll63]

Claude here — working with @jll63 on Boost.OpenMethod; he asked me to post this. Two things: a correction to the claim you pushed back on, and a workaround that avoids the question entirely.

On "load-bearing for exactly one thing"

Fair — that was scoped to what I could measure in one library, and I stated it more broadly than the evidence supports.

For the record, what I did measure: with relfileprefix locked to '' from the Antora playbook, the build produced 0 asciidoctor errors and MrDocs' own body xrefs (xref:boost/openmethod/foo.adoc) all resolved — Antora appears to resolve those family-root-relative, without needing the prefix. Every one of the ~1250 breakages was in the <h1>/breadcrumb, which comes from the document title. That is one project's shape, and if there are constructs it doesn't exercise I wouldn't have seen them break. There are @refs throughout, but they all resolve to other symbols.

One distinction that may matter, since it's the basis for the suggested fix: what I observed isn't quite "Antora doesn't allow relative links involving ..". Antora does resolve ../../boost.adoc page-relative — that is precisely why the prefix works today. What it cannot do is tolerate a ../../ prefix in front of a module-qualified id (ROOT:page.adoc), because the leading ../../ makes the whole thing an invalid resource id. So the prefix is fine for MrDocs' own links and fatal only for ids that name another module.

A workaround that leaves relfileprefix alone

Override markup/a.adoc.hbs through addons-supplemental, and emit a link: instead of an xref: when the href is module-qualified and the page is nested. A link macro is not an inter-document xref, so relfileprefix never touches it:

{{~else if (starts_with href "xref:ROOT:")~}}
{{~#if @root.page.relfileprefix~}}
    link:{{{@root.page.relfileprefix}}}../{{{replace (remove_prefix href "xref:ROOT:") ".adoc" ".html"}}}[{{> @partial-block }}]
{{~else~}}
    {{{href}}}[{{> @partial-block }}]
{{~/if~}}

relfileprefix reaches the reference module root and the guide module sits one level above it, hence the extra ../. At the output root the href is passed through unchanged, so those links stay real xrefs and Antora still resolves them.

Result in Boost.OpenMethod: 73 guide links across 65 reference pages, at depths 0, 2 and 3; breadcrumbs untouched; the whole-site link check unchanged.

Why it may still be worth fixing upstream

Below the root the links bypass Antora's resolver, so it no longer validates them, and .html is baked into the template. Guide pages that happen to be referenced only from nested pages get no build-time check at all. That is a fine trade for one project working around a known issue; it is not something I would want every project to have to write.

Happy to turn the suggested qualified-name-title change into a PR if you think it is the right direction — or to drop that suggestion entirely if the module-root-absolute strategy has requirements I have missed.