Doc 14675 fix Antora build errors (with Claude) - #4162
Open
osfameron wants to merge 6 commits into
Open
Conversation
Resolves a batch of Antora build errors surfaced for the server 8.0 component-version: typo'd link targets, `:` vs `/` module-separator mistakes, `.html` used where `.adoc` was needed, bare same-directory xrefs missing their subdirectory, a couple of browser "copy link to highlighted text" fragments pasted in as xref targets, and one image referenced from the wrong module. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- rest-bucket-create.adoc: two xrefs to xdcr-enable-crossclusterversioning.adoc were missing the `learn:` module prefix - rotate-encryption-at-rest-key.adoc / drop-encryption-deks.adoc: xrefs used `manage:security/...` instead of `manage:manage-security/...` - recover-data-with-xdcr.adoc: `add-a-node-and-rebalance.adoc` doesn't exist; real page is `add-node-and-rebalance.adoc` - fts-system-indexes.adoc: xref used a filesystem-style path (`n1ql/pages/n1ql-language-reference/searchfun.adoc`) instead of proper xref syntax (`n1ql:n1ql-language-reference/searchfun.adoc`) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- intro.adoc / starter-kits.adoc: each had a stray duplicate doctitle (level-0 heading) left over below the page attributes; removed the second one. - rbac.adoc / authentication-domains.adoc: `[backup-restore]` and `[saml-authentication]` used single brackets, which Asciidoctor treats as a section *style* rather than an anchor - this makes the section a "special section" that can't contain nested subsections. Changed to double brackets (`[[id]]`) so they're proper anchors. authentication-domains.adoc's anchor is actively linked from authentication-overview.adoc and configure-saml.adoc, so it had to be preserved rather than deleted. Verified locally with `asciidoctor` that both error types are gone and no new warnings were introduced. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Three xrefs into the sync-gateway component were broken: - `sync-gateway:refer/config-properties.adoc` -- that path was renamed; `configuration-properties-legacy.adoc` carries a page-alias for it, confirming this is the real successor page, so linking directly to it rather than relying on alias resolution. - Two uses of `sync-gateway::get-started-prepare.adoc` (double-colon, targeting the ROOT module) -- the real page lives in the `start-here` module, so the module name was missing. - One of those also targeted `#step-1create-a-bucket`, an anchor that never existed on the target page. Added a real anchor (`#lbl-create-bucket`) to docs-sync-gateway itself, matching that page's existing anchor-naming convention, and pointed this xref at it instead of guessing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Target page `install:upgrade-online.adoc` was deleted years ago. Sibling pages (upgrade-cluster-online-full-capacity.adoc, upgrade-cluster-online-reduced-capacity.adoc) already link to the correct successor and anchor: upgrade-procedure-selection.adoc#swap-rebalance. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
osfameron
requested review from
RayOffiah,
ggray-cb,
simon-dew and
supritha-kumar
September 8, 2026 13:51
Collaborator
Author
|
@ggray-cb oh, we did a drive-by on some of your links with Deleted only because the link itself was broken. Feel free to re-add them (to this PR branch) if you like. |
TimLFletcher
approved these changes
Sep 8, 2026
TimLFletcher
left a comment
Contributor
There was a problem hiding this comment.
Looks pretty common sense to me.
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
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.
This PR fixes 62 of the 81 Antora build errors that were showing up for server 8.0 (typo'd link targets, :// module-separator mistakes, .html used where .adoc was needed, browser-fragment junk pasted into xrefs, an orphaned page, etc.).
Done using Claude 🤖 so does need some testing. Done by feeding the latest
antora.logfrom a live build to get Actual Errors. I gave it https://docs-staging.couchbase.com/site-dependencies.json to allow it to resolve links toserver 8.0that are actually in other repositories, and pointed it at docs-sync-gateway.I've verified the PR by:
.adocwithout [],.html[], typo, etc.)Remaining errors not fixed
The remaining 19 all need a documentation/product decision rather than a mechanical fix: (Claude's wording below, apologies if any of the reasoning is incorrect, I've not verified. But the errors in the logs are real!)
FTS pages deleted in 2022 "redundant pages cleanup" (3 errors) cbft-bleve-moss.adoc, fts-search-response.adoc, manage-ui.adoc link to fts-queries.adoc, fts-consistency.adoc, fts-searching-from-the-ui.adoc — all removed years ago, content folded elsewhere. Needs someone to find/confirm the right current target for each.
compaction-rest-api.adoc split into three pages (2 errors) storage-settings.adoc and expiration.adoc both want a single "Compaction API" link, but that page is now three separate pages (rest-compact-post.adoc, rest-autocompact-global.adoc, rest-autocompact-per-bucket.adoc) with no overview page. Needs a call on which one (or whether to link all three).
Missing n1ql-rest-settings example includes (4 errors) general-settings.adoc includes 4 example files (query-settings-post-*.sh/json) from the cb-swagger repo's n1ql-rest-settings module, but that module has no examples/ directory at all. Looks like a generation-pipeline gap (cb-swagger has a Gradle/OpenAPI bundle step that may not be running), not a content typo — probably one for whoever owns that build.
Missing cbdocloader page + nav partial (1 error) nav.adoc includes tools:partial$nav-cbdocloader.adoc. Traced this to Nov 2021: docs-server deleted its own cbdocloader-tool.adoc and switched to including a partial from the backup repo's new tools module — but that partial (and the cbdocloader.adoc page itself) was never actually created there. Its siblings (nav-cbdatarecovery, nav-cbexport, nav-cbimport) all exist and work. This needs someone with access to the backup repo to author the missing page + nav partial.
docs-operator restructure (3 errors) couchbase-cloud-deployment.adoc links to operator:ROOT:install-gke.adoc, install-eks.adoc, install-aks.adoc. Traced to a "K8S-1268: Reorganize Docs" restructure in docs-operator — pages are gone, no obvious 1:1 successor found. Needs someone who knows the current operator docs structure.
Pinned SDK versions no longer resolving (5 errors) try-a-query.adoc (3.0@python-sdk), extended-attributes-fundamentals.adoc (3.4@java-sdk), scopes-and-collections.adoc (3.3@java-sdk, ×3). Oddly, the target pages and branches (release/3.0, release/3.4, release/3.3) do still exist in the SDK repos — so this probably isn't a dead link so much as this site build's playbook not including those particular old SDK version branches. Worth checking against whichever playbook is live, or just bumping these to a current SDK version.
Orphaned tutorial link (1 error) intro.adoc's "Developer Bootstrap Exercises" tile links to tutorials:quick-start:quickstart-docker-image-manual-cb65.adoc — a Couchbase 6.5-era Docker quickstart that no longer exists anywhere in docs-devex's tutorials module, and there's no obvious current tutorial that replaces it. Needs a call on whether to relink it to something else or just drop the tile.