[#317] Turn cross-guide xrefs into site links in asciidoc-to-pdf - #318
Merged
Merged
Conversation
…asciidoc-to-pdf Plain Asciidoctor knows neither the other guides nor the other Antora components, so the PDF goal left every xref that leaves the current guide as a dead link (opendj:install-guide:index.pdf, ../connectors-guide/x.pdf). The goal now renders from a copy of the sources (target/asciidoc/pdf-source) in which such xrefs become links to the page on the documentation site: - xref:component:module:page.adoc#a[] and xref:module:page.adoc#a[] - xref:../module/page.adoc#a[] A relative xref into the current guide becomes a same-guide xref; other xrefs are left as they are. The antora goal keeps reading the original sources. New goal parameters: siteUrl (default https://doc.openidentityplatform.org) and antoraComponent (default: projectName in lower case). Fixes OpenIdentityPlatform#317
maximthomas
approved these changes
Oct 5, 2026
maximthomas
left a comment
maximthomas
left a comment
Contributor
There was a problem hiding this comment.
praise: The rewrite lands where the dead links come from and leaves the Antora input alone.
preparePdfSourcerewrites a copy intarget/asciidoc/pdf-source, so theantoragoal reads the original sources whatever the goal order.- The component default uses
projectName.toLowerCase(Locale.ROOT). The consumers'projectNamevalues areOpenIDM,OpenAM,OpenDJandOpenIG. Under atrdefault locale, a plaintoLowerCase()would turnOpenIDMintoopenıdm. - The generated URLs match the site:
/openidm/index.html,/opendj/install-guide/index.htmland the other component roots return 200, and a missing page returns 404.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #317
Problem
asciidoc-to-pdfrenders each guide with plain Asciidoctor, which knows neither the other guides nor the other Antora components. Every xref that leaves the current guide ended up in the PDF as a dead link such asopendj:install-guide:index.pdfor../connectors-guide/chap-ldap.pdf#ldap-connector.Change
AsciidocToPdfMojonow copiestarget/asciidoc/sourcetotarget/asciidoc/pdf-source, rewrites xrefs in the copy, and renders from it. Theantoragoal keeps reading the original sources, whatever the goal order.xref:opendj:admin-guide:chap-replication.adoc#a[…]link:<siteUrl>/opendj/admin-guide/chap-replication.html#a[…]xref:install-guide:chap-install.adoc#a[…]link:<siteUrl>/<component>/install-guide/chap-install.html#a[…]xref:../connectors-guide/chap-ldap.adoc#a[…]link:<siteUrl>/<component>/connectors-guide/chap-ldap.html#a[…]xref:openam:ROOT:index.adoc[…],xref:openam::index.adoc[…]link:<siteUrl>/openam/index.html[…]xref:../<current guide>/page.adoc#a[…]xref:page.adoc#a[…](same guide)xref:#a[…],xref:page.adoc#a[…],xref:./page.adoc[…],xref:ROOT:attachment$…[…]New goal parameters:
siteUrl, defaulthttps://doc.openidentityplatform.organtoraComponent, defaultprojectNamein lower case. This matchesopenidm,opendj,openamandopenigin the site'santora.ymlfiles, so the four projects need no configuration change.Testing
AsciidocToPdfMojoTest(8 tests); all 48 tests of the module pass.Getting_Started.pdfandConnectors_Guide.pdffrom a copy of the OpenIDM doc sources with this plugin, adding the two cross-component xrefs from [#232] Fix legacy relative links and typos in the guides OpenIDM#234. No xref to another guide is left in the PDF sources, and all 27 distinct site pages return 200. The 10 section anchors exist on the site. The other 18 anchors are chapter ids such aschap-csv.html#chap-csv: Antora renders that heading as the page title without an id, so the link opens the top of the right page.Not in scope
The PDFs still contain dead
link:macros that are not xrefs:link:../attachments/…, legacylink:../../../opendj/…links (being replaced in OpenIdentityPlatform/OpenIDM#234), and ahhttps://typo in the OpenIDM Connectors Guide.