The PR preview includes only one component version linked to the PR branch. This allows us to reduce site content, focus on the changes included in the PR (less distraction for reviewers), and be quick to build and deploy.
This is what we've been doing since we migrated to Antora, and we want to keep doing it.
However, there has always been a problem with the resolution of xref targeting pages of other components or those of other versions of the same component. As the content of these component versions is not available during site construction, the xref is not resolved. This results in broken links in the preview and prevents PR reviewers from visually validating the links (to ensure that the targeted content is correct - and not just the link syntax).
Recently, we implemented Antora Atlas for automatic xref validation. Its main aim was to simplify the existing solution, which posed maintenance problems (all components and dependent versions had to be added when building a site, and the list of components was maintained manually). See
326
582
Antora Atlas is currently in alpha version and also requires an alpha version of Antora 3.2. The latest 3.2 alpha release does not include all the bug fixes present in the latest 3.1.x release. So, in order not to impact the production site with hidden side-effects due to unfixed issues, we've decided to:
keep using Antora 3.1.x for production build
use Antora 3.2 alpha for automatic xref validation
build the PR preview with the same version of Antora as the production site. The aim is to have a preview site as close as possible to the production site (at least for the generator - remember that the preview includes some of the content from the production site, a different navbar, ...) as this is where we validate the final content before pushing it into production.
As a result, links generated from xref cannot be resolved, so the HTML code produced contains broken links.
This indicates that the current situation is unclear/obvious to documentation editors and PR reviewers.
We could therefore consider running Atlas when generating the preview site. In short, this would mean using Antora 3.2 when building the preview.
We have at least the following options:
use Antora 3.2 alpha when building the preview and keep using Antora 3.1 for production build. This reduces eventual risks in production, but we may have differences in the generated content
use Antora 3.2 alpha everywhere. This would let us remove the dedicated job that validate the xref (will be included in the preview build) at the risk of new bugs in production due to Antora 3.2
In all cases, we must wait for an newer 3.2 alpha version. On 2023-09-06, based on latest Antora zulip chat, there was no date announced or mentioned for a new version. The Antora maintainers focus on other topics but moves could occur at the end of the year.
As a transitional measure, and for documentation repositories that may wish to mention it, we could provide an option in the "build-pr-preview" action to enable xref resolution:
build-setup action: add a install-antora-next input, default false, if true, install Antora 3.2 as currently done when running the xref validation workflow
build-pr-preview action: add a resolve-missing-component input, default to false. If true, enable Antora 3.2 by calling the build-setup action with the convenient input.
Current situation
The PR preview includes only one component version linked to the PR branch. This allows us to reduce site content, focus on the changes included in the PR (less distraction for reviewers), and be quick to build and deploy. This is what we've been doing since we migrated to
Antora, and we want to keep doing it.However, there has always been a problem with the resolution of xref targeting pages of other components or those of other versions of the same component. As the content of these component versions is not available during site construction, the xref is not resolved. This results in broken links in the preview and prevents PR reviewers from visually validating the links (to ensure that the targeted content is correct - and not just the link syntax).
Recently, we implemented
Antora Atlasfor automatic xref validation. Its main aim was to simplify the existing solution, which posed maintenance problems (all components and dependent versions had to be added when building a site, and the list of components was maintained manually). See326
582
Antora Atlas is currently in alpha version and also requires an alpha version of Antora 3.2. The latest 3.2 alpha release does not include all the bug fixes present in the latest 3.1.x release. So, in order not to impact the production site with hidden side-effects due to unfixed issues, we've decided to:
As a result, links generated from xref cannot be resolved, so the HTML code produced contains broken links.
Perspectives
We receive recurrent questions about "the links are broken", "there is an issue in the preview with the links", "why don't I see the link to bcd from my PR for bonita 2021.2", ..... For instance, see https://github.com/bonitasoft/bonita-test-toolkit-doc/pull/51#pullrequestreview-1607004559
This indicates that the current situation is unclear/obvious to documentation editors and PR reviewers. We could therefore consider running Atlas when generating the preview site. In short, this would mean using Antora 3.2 when building the preview. We have at least the following options:
In all cases, we must wait for an newer 3.2 alpha version. On 2023-09-06, based on latest Antora zulip chat, there was no date announced or mentioned for a new version. The Antora maintainers focus on other topics but moves could occur at the end of the year.
As a transitional measure, and for documentation repositories that may wish to mention it, we could provide an option in the "build-pr-preview" action to enable xref resolution: