Conversation
The workflow sidestepped the package.json pin with an unpinned `npm i antora`, so every publish built with whatever was current, on Node 18, which is past end of life. Move to 3.2.0 with a matching lockfile, install with `npm ci`, and use Node 22. The content lives in the nrepl repo, so a push here is rarely what changes the site; the last deploy was three months old with seventeen doc commits waiting. A daily scheduled build picks them up, and a repository_dispatch lets the nrepl repo ask for a rebuild right away.
The playbook still carried the Universal Analytics id, which Google stopped processing in 2023, so the site has been reporting nothing since.
The scripts loaded the floating @Alpha dist tag, and the stylesheet still carried rules for the DocSearch v2 autocomplete and for a Lunr search box that was never installed. The header's Home link was href="#".
Antora only exits non-zero on fatal errors, so the unresolved xref in the 1.6 and 1.7 docs has been deployed as a dead link for months. A failure level of warn turns those into a red build instead. latest_version_segment did nothing: master is unversioned, which Antora treats as the latest version and publishes without a version segment, so /nrepl/latest/ was a 404 all along. linkattrs has been on by default since Asciidoctor 2.
Both releases link to the TLS page with an xref that Antora can't resolve. The v1.6.0-antora and v1.7.0-antora tags carry the fix, the way earlier releases were handled.
The installation page presents its per-build-tool snippets as tabs, which needs @asciidoctor/tabs on the site. Its stylesheet and script come straight from the npm package, which means listing the supplemental UI files one by one instead of pointing at the directory.
The README's Docker example couldn't find the playbook, showed start_path: docs for a directory called doc, and talked about adding modules that don't exist. The contributing page in the nrepl repo told people to edit the production playbook to point at their clone; the new antora-playbook-local.yml builds ../nrepl as checked out, uncommitted changes included, so that's no longer necessary. The Makefile listed a deploy target that doesn't exist.
bbatsov
force-pushed
the
modernize-site-build
branch
from
September 13, 2026 07:14
ba319fb to
929a140
Compare
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
1 participant
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.
The publish workflow installed an unpinned Antora on Node 18 and only ran on pushes here, so the live site was three months behind the docs. It now builds with
npm cion Node 22 from a 3.2.0 lockfile, once a day, and whenever nrepl asks via repository_dispatch (nrepl/nrepl#486 adds the sender).Also: the GA4 measurement id replaces the Universal Analytics one that stopped counting in 2023, DocSearch is pinned to v3 instead of the floating
@alphatag, broken references now fail the build instead of going live (the 1.6 and 1.7 docs had one each, now built from-antoratags that carry the fix), the tabs extension is wired in for the installation page, and there's a playbook for previewing a local nrepl checkout. Same shape as the docs.cider.mx changes from last week.