DOC-14627: Polaris rebranding - "Operational Insights" by osfameron · Pull Request #910 · couchbase/docs-site

osfameron · 2026-09-02T11:41:02Z

Antora 3.2.0 exposes ContentCatalog#createFile, which lets a component publish under a different URL segment than its registered name without actually renaming the component - so xrefs/includes into it (e.g. xref:analytics:...) keep resolving normally. lib/override-url-component.js implements this: for any component version with an override-url-component asciidoc attribute set (docs-columnar's analytics component sets it to operational-insights), it remaps out/pub on that version's page/image/ attachment files by building a mock src with the swapped component and lifting the computed out/pub from ContentCatalog#createFile, then patches componentVersion.url to match since it's cached at registration time.

Also fixes scripts/preview, which broke under 3.2.0's now-stricter --url validation: printf %q escaping plus unquoted re-expansion of $ANTORA could split a path containing special characters across multiple argv entries. Replaced with a bash array invocation, which passes the URL through as a single clean argument with no shell re-parsing needed.

Copilot

🟡 Changes recommended

The URL-override extension is only wired into a generated preview playbook (not its *.diff source nor the main/staging playbooks), so the behavior won’t reliably apply to real builds and may be lost on regeneration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR upgrades the site build tooling to Antora 3.2.x and introduces an Antora extension intended to publish a component under an alternate URL segment (to support the Analytics → Operational Insights URL rename without renaming the component itself).

Changes:

Bump Antora dependency from ~3.1 to ~3.2 (and update the lockfile accordingly).
Fix scripts/preview Antora invocation to avoid argv-splitting by using a bash array.
Add lib/override-url-component.js and enable it in the preview playbook.

File summaries

File	Description
scripts/preview	Switch Antora invocation to a bash array to preserve `--url` as a single argument.
package.json	Bump Antora to `~3.2`.
package-lock.json	Lockfile updates for Antora 3.2.0 and transitive dependency/engine changes.
lib/override-url-component.js	New Antora extension to remap published `out/pub` paths based on an AsciiDoc attribute.
antora-playbook.preview.yml	Enables the new extension for preview builds.

Review details

Files reviewed: 5/6 changed files
Comments generated: 4
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

    - ./lib/report-tree.js
    - ./lib/site-stats-extension.js
    - ./lib/component-stats.js
+    - ./lib/override-url-component.js


@@ -283,16 +283,16 @@ else
    cd $DOCS_SITE
    echo

-    ANTORA="npx antora --extension lib/preview.js antora-playbook.preview.yml --stacktrace --url '$(pwd)/preview'"
+    ANTORA=(npx antora --extension lib/preview.js antora-playbook.preview.yml --stacktrace --url "$(pwd)/preview")


    - ./lib/report-tree.js
    - ./lib/site-stats-extension.js
    - ./lib/component-stats.js
+    - ./lib/override-url-component.js


+module.exports.register = function () {
+  this.once('contentClassified', ({ contentCatalog }) => {
+    contentCatalog.getComponents().forEach((component) => {
+      component.versions.forEach((componentVersion) => {
+        const overrideComponent = componentVersion.asciidoc?.attributes?.['override-url-component']


…ytics rename Antora 3.2.0 exposes ContentCatalog#createFile, which lets a component publish under a different URL segment than its registered name without actually renaming the component - so xrefs/includes into it (e.g. xref:analytics:...) keep resolving normally. lib/override-url-component.js implements this: for any component version with an override-url-component asciidoc attribute set (docs-columnar's analytics component sets it to operational-insights), it remaps out/pub on that version's page/image/ attachment files by building a mock src with the swapped component and lifting the computed out/pub from ContentCatalog#createFile, then patches componentVersion.url to match since it's cached at registration time. Also fixes scripts/preview, which broke under 3.2.0's now-stricter --url validation: printf %q escaping plus unquoted re-expansion of $ANTORA could split a path containing special characters across multiple argv entries. Replaced with a bash array invocation, which passes the URL through as a single clean argument with no shell re-parsing needed. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…tora.yml Redirecting individual versions of a component never makes sense (a version-specific rename would be a new product/component instead), so per-version antora.yml attributes were the wrong place to configure this - it meant touching every branch of the content repo just to rename a component. Move the config into the playbook instead, as a `map` of target name to legacy/renamed source names, e.g.: - require: ./lib/override-url-component.js map: operational-insights: [analytics, columnar] For each `from` name, the extension now decides automatically whether it's still a live registered component (analytics, mid-rename - remap its out/pub as before) or already retired with no content source of its own (columnar, since the legacy-columnar-component branch was dropped in 55e2505 - add a single whole-prefix redirect instead). That's the moral equivalent of ContentCatalog#addSplatAlias, inlined: addSplatAlias requires a non-empty version segment on the "from" side, which a retired/unversioned name doesn't have, and since versions were never going to be distinguished anyway, none of its version-segment bookkeeping is needed - h/t Dan Allen for confirming this is reasonable to build directly against the content catalog rather than fight the version-segment guard. Also fixes a copy-paste bug in the sample nginx rewrites (the /analytics/ rule was matching against ^/columnar/ instead of ^/analytics/, so it would never have fired). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…ames remapLiveComponent() moves a live component's own files to new URLs outright rather than aliasing the old ones, so it doesn't help a bookmark to one of their old per-page URLs (e.g. /analytics/intro/intro.html) - only the component's own root got covered, via Antora's built-in synthetic index-page alias. Call addLegacyAlias() unconditionally, alongside remapLiveComponent() when the name is still live, so every 'from' name gets the whole-prefix /from/* -> /to/* redirect regardless. Verified via the real redirect-producer that this doesn't conflict with Antora's own synthetic root-index alias for a live component: nginx's `location =` exact match for /analytics/index.html (pointing straight at the real start page) takes precedence over our `location ^~` prefix match for everything else under /analytics/*, so both apply correctly together. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

remapLiveComponent() builds a mock src to get ContentCatalog#createFile to compute out/pub for the new component name, but the mock's src.component (the target name, e.g. operational-insights) isn't itself a registered component - so createFile's internal getComponentVersion(src.component, src.version) lookup fails, and it falls back to a bare {version} object with no cached activeVersionSegment and no component link. For a component using the redirect:to latest-version-segment strategy (e.g. enterprise-analytics, urls.latest_version_segment_strategy: redirect:to), that fallback silently computes the raw version number instead of resolving to 'current' for the latest version - so the live remap published the latest version at .../2.2/... under the new name, with nothing at all left at .../current/..., where real navigation actually points. Fix: pass the real componentVersion through as src.componentVersion. createFile only does the lookup when componentVersion is absent, so this short-circuits straight to the correct, already-resolved activeVersionSegment (verified via a full register/version/current cycle against the real 3.2.0 ContentCatalog). This also settles the "redirects always land on current" question: that's Antora's own pre-existing redirect:to alias for the numbered version (more specific nginx location, so it fires before our whole-prefix rule and chains into it) - unrelated to this bug, and not something to change. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

via Claude

to better test build/xref errors

@Rebecca-Martinez007

via @Rebecca-Martinez007

mblow

A few naming and nav comments on the Operational Insights parts of this PR, inline below.

mblow · 2026-10-06T18:15:08Z

+          "color": "#ed9426",
+          "subGroups": [
+            {
+              "title": "Operational Insights Enterprise",


These submenu titles sit under the Operational Insights menu, so in the top nav we get "Operational Insights" twice and "Insights" once. Can the subgroup titles be:

Operational Insights Enterprise → Enterprise

Operational Insights Capella → Capella

Insights SDKs → SDKs

Analytics Connectors → Connectors

(The same applies to the preview playbooks.)

mblow · 2026-10-06T18:15:09Z

+              "expandHeaderLevels": 1
+            },
+            {
+              "title": "Legacy Analytics SDKs",


I don't think Legacy Analytics SDKs belongs in this menu at all: operational-insights-sdk.adoc already links to these SDKs. Removing the subgroup means *-analytics-sdk and *-columnar-sdk need another home, such as the SDKs subgroup, so that their pages stay grouped.

I'd also drop the "Legacy Analytics" name everywhere. These are the last version of the same product, not a legacy one, so Analytics SDKs (Deprecated) would be better.

mblow · 2026-10-06T18:15:09Z

+              "expandHeaderLevels": 1
+            },
+            {
+              "title": "Legacy Analytics SDKs",


Same as in antora-playbook.yml: please drop this subgroup from the menu, and move its components into the SDKs subgroup.

mblow · 2026-10-06T18:15:09Z

-== SDK APIs to work with Enterprise Analytics
+== SDK APIs to work with Operational Insights
+
+TIP: This section covers Couchbase's legacy Analytics SDKs.


Please avoid "legacy" here. These SDKs are the last version of the same product, and they're deprecated now rather than "in due course". Something like:

This section covers the Analytics SDKs, which are deprecated. They have been superseded by the xref:operational-insights-sdk.adoc[Operational Insights SDKs].

mblow · 2026-10-06T18:15:09Z

+| xref:enterprise-analytics:intro:intro.adoc[Operational Insights Enterprise]
+a|
+* xref:operational-insights-sdk.adoc[Insights SDKs]
+* xref:analytics-sdk.adoc[Legacy Analytics SDKs]


Rename to match:

Suggested change

* xref:analytics-sdk.adoc[Legacy Analytics SDKs]

* xref:analytics-sdk.adoc[Analytics SDKs (Deprecated)]

mblow · 2026-10-06T18:15:09Z

+
+.SDK Compatibility with Operational Insights Service
+|===
+| Operational-Insights solution | Development option


"Operational-Insights" shouldn't be hyphenated. Perhaps:

Suggested change

| Operational-Insights solution | Development option

| Operational Insights offering | Development option

mblow · 2026-10-06T18:15:09Z

+* xref:analytics-sdk.adoc[Legacy Analytics SDKs]
+
+| xref:operational-insights:intro:intro.adoc[Operational Insights Capella]
+| xref:columnar-sdk.adoc[Columnar (Operational Insights Capella) SDKs]


Columnar isn't Operational Insights Capella. Columnar is the SDK's name from two rebrandings ago, and it happens to be the SDK required today for Capella deployments that don't connect through private link. Please label it just Columnar SDKs:

Suggested change

| xref:columnar-sdk.adoc[Columnar (Operational Insights Capella) SDKs]

| xref:columnar-sdk.adoc[Columnar SDKs]

mblow · 2026-10-06T18:15:09Z

+
+=== SDK APIs to work with Operational Insights Capella
+
+Columnar SDKs, are similar to the Operational Insights SDKs.


This should say what the Columnar SDKs are for today: they're required for Operational Insights Capella deployments that don't connect through private link. They aren't "the" Operational Insights Capella SDKs, and the text shouldn't imply a rename of the service.

mblow · 2026-10-06T18:15:09Z

+| xref:operational-insights:intro:intro.adoc[Operational Insights Capella]
+| xref:columnar-sdk.adoc[Columnar (Operational Insights Capella) SDKs]
+
+| xref:server:learn:services-and-indexes/services/operational-insights-service.adoc[CBAS (Couchbase Operational-Insights Service)] 


This row looks like it got caught by a search-and-replace. CBAS is the Couchbase Server Analytics Service, which hasn't been renamed, and operational-insights-service.adoc doesn't exist in the Server docs. Line 158 of this file already uses the correct link:

Suggested change

| xref:server:learn:services-and-indexes/services/operational-insights-service.adoc[CBAS (Couchbase Operational-Insights Service)]

| xref:server:learn:services-and-indexes/services/analytics-service.adoc[CBAS (Couchbase Analytics Service)]

mblow · 2026-10-06T18:15:09Z

+=== icon:rocket[] Real Time Analytics with Operational Insights
+
+* xref:enterprise-analytics:intro:intro.adoc[Operational Insights Enterprise] brings the power of NoSQL to the world of analytics -- self-managed, in your private cloud or data centre.
+* xrefanalytics:intro:intro.adoc[Operational Insights Capella] brings the power of NoSQL to the world of analytics -- managed for you as a Capella service


The colon after xref is missing, so this renders as literal text (xrefanalytics:intro:intro.adoc[…]) on the preview2 start page:

Suggested change

* xrefanalytics:intro:intro.adoc[Operational Insights Capella] brings the power of NoSQL to the world of analytics -- managed for you as a Capella service

* xref:analytics:intro:intro.adoc[Operational Insights Capella] brings the power of NoSQL to the world of analytics -- managed for you as a Capella service

osfameron requested a lite review from Copilot September 2, 2026 11:41

Copilot started reviewing on behalf of osfameron September 2, 2026 11:41 View session

Copilot AI reviewed Sep 2, 2026

View reviewed changes

osfameron changed the title ~~DOC-14627: bump Antora to 3.2, URL override for Analytics rename~~ DOC-14627: Polaris rebranding - "Operational Insights" Sep 3, 2026

osfameron and others added 17 commits September 22, 2026 15:04

Sample nginx rewrites

354d363

DOC-14627 back out columnar legacy component hack

3a30239

Operational Insights nav

17a8335

remove specific nginx rewrites, as we handle in Antora now

5bfed27

point preview2 to rename branch

7f58c25

DOC-14627 update text based on PM mockup

1ac41d0

via Claude

update preview2

2adc1f6

add more components

a56d2c0

to better test build/xref errors

add server

2b04ad6

watermark

2ae91c2

update EA branch

c71d6f9

fix

e92002f

Update antora-playbook.preview2.yml

229c33f

osfameron force-pushed the DOC-14627-analytics-url-rename branch from 272de68 to 229c33f Compare September 22, 2026 14:08

osfameron added 2 commits September 22, 2026 15:08

patch staging playbook

da64a8d

update IA and polaris sha

2ad9367

osfameron mentioned this pull request Sep 25, 2026

DOC-14627 analytics url rename essentials #913

Merged

osfameron added 5 commits September 28, 2026 16:08

merge-prs script, applied to EA 3.0

0e8b25c

bump playbook

4c74f7c

Branches from docs-ai / capella

8f8b04c

via @Rebecca-Martinez007

point to Harini's rename branch + removal of page-aliases

62bf7d7

update merge-prs script

2331259

osfameron and others added 11 commits September 29, 2026 15:51

update docs-columnar preview branch

25cfe11

prod-237 Operational Insights badge

b22b602

SDK work for October release, and new top nav (#918)

a8a5d6f

Updates to Richard's IA sketch

31f0d7c

oi common files branch fix

35da59c

update preview2 playbook

1553ecf

docs-site changes for Operational Insights

9ce25eb

change wording on OI landing page

d332121

correct name of start-here

82f37be

Update to Antora Atlas via @mojavelinux

8bc51c7

update preview2 playbook

06f32c8

mblow reviewed Oct 6, 2026

View reviewed changes

osfameron and others added 5 commits October 8, 2026 18:39

hide preview link

643fb88

Updated the card content

dbc06cf

Included a new note

7f10aad

Update docs-capella branch for preview

25dc83a

fixes to merge-prs

fed4fd6

Navigation Menu

Repository navigation

DOC-14627: Polaris rebranding - "Operational Insights" - #910

DOC-14627: Polaris rebranding - "Operational Insights"#910
osfameron wants to merge 40 commits into
masterfrom
DOC-14627-analytics-url-rename

osfameron commented Sep 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mblow left a comment

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

mblow Oct 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

	* xref:analytics-sdk.adoc[Legacy Analytics SDKs]
	* xref:analytics-sdk.adoc[Analytics SDKs (Deprecated)]

	\| Operational-Insights solution \| Development option
	\| Operational Insights offering \| Development option

	\| xref:columnar-sdk.adoc[Columnar (Operational Insights Capella) SDKs]
	\| xref:columnar-sdk.adoc[Columnar SDKs]


		=== SDK APIs to work with Operational Insights Capella

		Columnar SDKs, are similar to the Operational Insights SDKs.

	\| xref:server:learn:services-and-indexes/services/operational-insights-service.adoc[CBAS (Couchbase Operational-Insights Service)]
	\| xref:server:learn:services-and-indexes/services/analytics-service.adoc[CBAS (Couchbase Analytics Service)]

	* xrefanalytics:intro:intro.adoc[Operational Insights Capella] brings the power of NoSQL to the world of analytics -- managed for you as a Capella service
	* xref:analytics:intro:intro.adoc[Operational Insights Capella] brings the power of NoSQL to the world of analytics -- managed for you as a Capella service

Conversation

osfameron commented Sep 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

mblow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants