<div dir="ltr"><div dir="ltr"><div>I was exploring GitLab's CI/CD (continuous 
integration / delivery) functionality last night/this morning and decided to try building 
our Antora-based documentation this way with the output hosted on GitLab
 Pages. <br></div><div><br></div><div>It works quite nicely. I've posted a rough implementation branch at <a href="https://gitlab.com/evergreen-library-system/evergreen-library-system/-/commits/gitlab-antora-build" target="_blank">https://gitlab.com/evergreen-library-system/evergreen-library-system/-/commits/gitlab-antora-build</a> <br></div><div><br></div><div>As
 you can see, it's just a couple of YAML files; .gitlab-cy.yml defines 
the "pages" step, and .gitlab-antora.yml defines a custom Antora 
playbook for the Docker environment. The CI/CD piece means that a new 
build would be triggered by every commit.<br></div><div><br></div><div>The output is visible at <a href="https://evergreen-library-system.gitlab.io/evergreen-library-system/docs/latest/index.html" target="_blank">https://evergreen-library-system.gitlab.io/evergreen-library-system/docs/latest/index.html</a></div><div><br></div><div>It's
 nice to see the current list of build errors, such as missing references or media files, at a glance: <a href="https://gitlab.com/evergreen-library-system/evergreen-library-system/-/jobs/1927489146" target="_blank">https://gitlab.com/evergreen-library-system/evergreen-library-system/-/jobs/1927489146</a><br></div><div><br></div><div></div><div><div>If we decided to merge this, we would want to modify the configuration
 so that it only watches a given branch (our main branch, most likely), 
rather than triggering a new build for every commit  on every branch. But most of the doc build could also be reused as an 
integration test to be run against every branch / merge request. If a 
test fails, then the merge request gets flagged, the errors get reported as a comment right on the branch/merge request (instead of having to dig into the job details), and the branch could be blocked from merging
until the problem is resolved.</div></div><div><br></div><div>I'm using the Node.js npx command to avoid having to globally install 
the npm modules. npx is a nice way to avoid conflicts between 
requirements for different 
module versions at the global level and to avoid having to run commands 
as root. When you prefix a command with "npx", such as "npx antora", it 
searches for the command within the local project's node_modules path 
instead of globally. Could be useful elsewhere in Evergreen.</div><div><br></div><div>Notes:</div><div>* I updated the build process to use the just-released Antora 3 and the corresponding Antora lunr-extension.</div><div>* I have not applied the Evergreen 
customizations of CSS, the header menu, or the contact DIG message in 
the footer. Antora 3 has moved to "extensions" which are lighter weight 
than our current approach of cloning and tweaking the Antora default UI 
repository.</div><div>* In addition to the basic "does Antora build the docs without errors" integration test, we could add a style checker like Vale (<a href="https://gitlab.com/jdkato/vale" target="_blank">https://gitlab.com/jdkato/vale</a>)
 as another test for the documentation. Vale can flag spelling errors 
(with a custom dictionary of course) and grammatical issues like passive
 voice, etc.</div></div></div>