DOC-14627 analytics url rename essentials - #913
Merged
Merged
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>
…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
We want to merge: * Antora 3.2.0 * the lib/override-url-component.js extension but NOT any live config, or the landing page.
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
2 participants
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 is slightly cut down version of #910
It upgrades Antora, and adds the extension, with config for .preview2 only (but which @RichardSmedley can use to test IA branch)
(The PR #910 should then be trivially mergeable later with the landing page and updates to antora-playbook.yml itself)