doc-maven-plugin: asciidoc-to-pdf leaves cross-guide and cross-component xrefs as dead links #317

The asciidoc-to-pdf goal of doc-maven-plugin produces dead links for every xref that leaves the guide being rendered. The link text is right, but the target does not exist.

Where

AsciidocToPdfMojo renders each guide's index.adoc with plain asciidoctor-maven-plugin 2.2.6 + asciidoctorj-pdf 2.3.18. Plain Asciidoctor knows nothing about Antora components or about the other guides, so it keeps the xref path and only swaps .adoc for .pdf. AntoraMojo converts the same sources correctly for the site, so this affects the PDFs only.

What the PDFs get

Rendered with plain Asciidoctor (outfilesuffix=.pdf):

• The first two are cross-component xrefs. OpenIDM now uses them for links to the OpenDJ and OpenAM guides ([#232] Fix legacy relative links and typos in the guides OpenIDM#234, e.g. Getting_Started.pdf and Samples_Guide.pdf). The old link:../../../opendj/… links they replace were dead in the PDFs too, so this is not a regression of that PR.
• The third is the ordinary cross-guide xref already used across the OpenIDM guides. It was dead in the PDFs before as well.

OpenAM, OpenDJ and OpenIG run the same goal (openam-doc-source, opendj-doc-generated-ref, openig-doc). I have only checked OpenIDM, but their PDFs should have the same problem wherever their guides link to another guide or component.

Expected

An xref that leaves the current guide should open the matching page on https://doc.openidentityplatform.org, which is where the PDFs point readers anyway. The site layout is <site>/<component>/<module>/<page>.html#<anchor>, for example https://doc.openidentityplatform.org/opendj/admin-guide/chap-replication.html#read-ecl-as-regular-user.

Possible fix

Before rendering, AsciidocToPdfMojo could rewrite (on a copy of the sources, or through an Asciidoctor extension) the xrefs that leave the current guide into absolute link:s:

• xref:<component>:<module>:<page>.adoc[#anchor][text] → link:<site>/<component>/<module>/<page>.html[#anchor][text]
• xref:../<module>/<page>.adoc[#anchor][text] → link:<site>/<this component>/<module>/<page>.html[#anchor][text]

The site URL and the project's own component name are not known to the plugin today: the component name lives in the site repository's antora.yml (e.g. openidm). Both would have to become goal parameters, for example siteUrl defaulting to https://doc.openidentityplatform.org and antoraComponent.

xrefs inside the same guide (xref:#anchor[…], xref:chap-x.adoc#anchor[…]) are out of scope and should be left as they are.

References

• Raised in the review of [#232] Fix legacy relative links and typos in the guides OpenIDM#234: [#232] Fix legacy relative links and typos in the guides OpenIDM#234 (review)