DOC-14627: Polaris rebranding - "Operational Insights" - #910
Open
osfameron wants to merge 10 commits into
Open
Conversation
…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>
Contributor
There was a problem hiding this comment.
🟡 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.1to~3.2(and update the lockfile accordingly). - Fix
scripts/previewAntora invocation to avoid argv-splitting by using a bash array. - Add
lib/override-url-component.jsand 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 |
Comment on lines
282
to
+286
| DOCS_SITE=$(realpath $0/../..) | ||
| 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 |
Comment on lines
+21
to
+25
| module.exports.register = function () { | ||
| this.once('contentClassified', ({ contentCatalog }) => { | ||
| contentCatalog.getComponents().forEach((component) => { | ||
| component.versions.forEach((componentVersion) => { | ||
| const overrideComponent = componentVersion.asciidoc?.attributes?.['override-url-component'] |
…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
osfameron
changed the title
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.
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.