@redpanda-data/docs-extensions-and-macros 5.54.0 → 5.55.0

package/extensions/aggregate-terms.js

@@ -127,32 +127,46 @@ module.exports.register = function ({ config }) {
   })
 
   .on('contentClassified', ({ siteCatalog, contentCatalog }) => {
-    const components = contentCatalog.getComponents();
+    // Appends every term, by category, to a glossary page.
+    function mergeTerms (glossaryPage) {
+      let glossaryContent = glossaryPage.contents.toString('utf8');
+      Object.keys(siteCatalog.termsByCategory).sort().forEach(category => {
+        let categoryContent = `\n\n== ${category}\n`;
+        siteCatalog.termsByCategory[category].sort((a, b) => a.name.localeCompare(b.name)).forEach(term => {
+          categoryContent += `\n\n${processTermContent(term.content)}`;
+        });
+        glossaryContent += categoryContent;
+      });
+      glossaryPage.contents = Buffer.from(glossaryContent, 'utf8');
+    }
+
     try {
-      components.forEach(({ versions }) => {
+      // With `glossarypage`, one page holds the glossary for the whole site,
+      // and every component's glossterm links point at it. Glossary pages
+      // components still have are filled too, so they stay complete until
+      // they are removed.
+      let sitePage = null;
+      if (config.glossarypage) {
+        sitePage = contentCatalog.resolvePage(config.glossarypage);
+        if (sitePage) {
+          mergeTerms(sitePage);
+          logger.info(`Merged terms into the site glossary ${config.glossarypage}.`);
+        } else {
+          logger.warn(`The glossarypage ${config.glossarypage} does not exist, so each component links to its own reference:glossary.adoc instead.`);
+        }
+      }
+
+      contentCatalog.getComponents().forEach(({ versions }) => {
         versions.forEach(({ name: component, version, asciidoc, title }) => {
           if (component == 'shared') return;
+          if (sitePage) asciidoc.attributes['glossary-page'] = config.glossarypage;
 
           const glossaryPage = contentCatalog.resolvePage(`${version ? version + '@' : ''}${component}:reference:glossary.adoc`);
-
-          if (glossaryPage) {
-            asciidoc.attributes['glossary-page'] = 'reference:glossary.adoc';
-            let glossaryContent = glossaryPage.contents.toString('utf8');
-
-            Object.keys(siteCatalog.termsByCategory).sort().forEach(category => {
-              let categoryContent = `\n\n== ${category}\n`;
-
-              siteCatalog.termsByCategory[category].sort((a, b) => a.name.localeCompare(b.name)).forEach(term => {
-                let processedContent = processTermContent(term.content);
-                categoryContent += `\n\n${processedContent}`;
-              });
-
-              glossaryContent += categoryContent;
-            });
-
-            glossaryPage.contents = Buffer.from(glossaryContent, 'utf8');
+          if (glossaryPage && glossaryPage !== sitePage) {
+            if (!sitePage) asciidoc.attributes['glossary-page'] = 'reference:glossary.adoc';
+            mergeTerms(glossaryPage);
             logger.info(`Merged terms into glossary for ${component} component${version ? ' version ' + version : ''}.`);
-          } else {
+          } else if (!glossaryPage && !sitePage) {
             logger.info(`Skipping ${title} ${version ? ' version ' + version : ''} - No glossary page (reference:glossary.adoc) found`);
           }
         });

package/extensions/modify-connect-tag-playbook.js

@@ -75,6 +75,16 @@ const LOCAL_DIR_ENV = 'REDPANDA_CONNECT_DOCS_DIR'
 // the probe fallback tries, when the latest release has no asset yet.
 const FALLBACK_RELEASE_LIMIT = 10
 const FALLBACK_PROBE_LIMIT = 3
+// Dating pages by release (only when add-git-dates is in the playbook): the
+// page size of the releases listing, the first release that has the asset
+// (no older release can be compared), and the most older releases the walk
+// downloads per build.
+const DATE_RELEASE_PAGE_SIZE = 100
+const FIRST_ASSET_RELEASE = 'v4.113.0'
+const DATE_RELEASE_LIMIT = 10
+// How deep the walk follows includes inside the asset's own partials, such as
+// bloblang/methods.adoc including every bloblang-methods/* partial.
+const NESTED_INCLUDE_DEPTH = 3
 
 // HTTPS, SSH (ssh://), and scp-style (git@host:owner/repo) URLs are all
 // remote content sources in Antora.
@@ -284,6 +294,163 @@ async function findOlderReleaseWithAsset (latestTag, url, logger) {
   return null
 }
 
+// The resource keys (`partial$<relative>`, `example$<relative>`) of generated
+// files that differ between two releases' assets, or are new in `files`.
+function changedReferenceKeys (files, previousFiles) {
+  const before = new Map()
+  for (const f of previousFiles) {
+    const r = asset.toResource(f.path)
+    if (r && !before.has(`${r.family}$${r.relative}`)) before.set(`${r.family}$${r.relative}`, f.contents)
+  }
+  const changed = new Set()
+  const seen = new Set()
+  for (const f of files) {
+    const r = asset.toResource(f.path)
+    if (!r || r.family === 'attachment') continue
+    const key = `${r.family}$${r.relative}`
+    // addConnectDocs retains the first copy of a resource in an asset.
+    if (seen.has(key)) continue
+    seen.add(key)
+    const old = before.get(key)
+    if (old === undefined || Buffer.compare(Buffer.from(old), Buffer.from(f.contents)) !== 0) changed.add(key)
+  }
+  return changed
+}
+
+// Includes of the connect components module in a page: `partial$x` and
+// `example$x` keys. In the connect component's own components module the
+// module may be implicit; elsewhere only fully qualified includes count. With
+// a content catalog, only files this asset added count, and includes inside
+// those files are followed too (up to NESTED_INCLUDE_DEPTH levels), so a page
+// that includes an aggregate partial is dated by the partials it pulls in.
+const INCLUDE_RX = /^include::([^[\s]+)\[/gm
+function includeKey (target, src) {
+  const own = src.component === COMPONENT && src.module === asset.MODULE
+  const q = target.match(/^connect:components:((?:partial|example)\$.+)$/) ||
+    (own ? target.match(/^(?:components:)?((?:partial|example)\$.+)$/) : null)
+  return q ? q[1] : null
+}
+function connectIncludes (page, contentCatalog, origin) {
+  const keys = []
+  const seen = new Set()
+  const visit = (file, depth) => {
+    for (const m of file.contents.toString('utf8').matchAll(INCLUDE_RX)) {
+      const key = includeKey(m[1], file.src)
+      if (!key) continue
+      if (!contentCatalog) {
+        keys.push(key)
+        continue
+      }
+      const included = contentCatalog.resolveResource(m[1], file.src)
+      // Only files inserted from this asset can acquire a release date.
+      if (!included || included.src.origin !== origin || seen.has(included)) continue
+      seen.add(included)
+      keys.push(key)
+      if (depth < NESTED_INCLUDE_DEPTH) visit(included, depth + 1)
+    }
+  }
+  visit(page, 1)
+  return keys
+}
+
+// Marks pages with the newest change date of their included asset references.
+// Catalog resolution excludes retained duplicates and respects each version.
+// Cloud stubs inherit the date of the connect page they actually include.
+function markReferenceChanges (contentCatalog, dates, origin) {
+  if (!dates.size) return 0
+  const marked = new Set()
+  const pages = contentCatalog.getPages()
+  const mark = (page, date) => {
+    if (!date) return
+    if (!page.connectReferenceModified || date > page.connectReferenceModified) page.connectReferenceModified = date
+    marked.add(page)
+  }
+  for (const page of pages) {
+    for (const key of connectIncludes(page, contentCatalog, origin)) mark(page, dates.get(key))
+  }
+  for (const page of pages) {
+    for (const m of page.contents.toString('utf8').matchAll(INCLUDE_RX)) {
+      if (!/^connect:([^:$]+):([^$]+\.adoc)$/.test(m[1])) continue
+      const included = contentCatalog.resolvePage(m[1], page.src)
+      if (marked.has(included)) mark(page, included.connectReferenceModified)
+    }
+  }
+  return marked.size
+}
+
+// The date of the newest release that changed each of `keys`, as a Map of
+// key to YYYY-MM-DD. It compares the release with older releases that have
+// the asset, newest first, so a file left unchanged by the current release
+// keeps the date of the release that last changed it. Bounded so the cost
+// does not grow with every connect release: the listing stops paging at the
+// first release older than FIRST_ASSET_RELEASE, and the walk downloads at
+// most DATE_RELEASE_LIMIT older releases. A file still unchanged at the end
+// of the walk gets no date. A failed listing, download, or read only costs
+// dates: it logs a warning, and every file not dated yet keeps its git date.
+async function referenceReleaseDates (tag, files, keys, logger) {
+  const dates = new Map()
+  if (!keys.size) return dates
+  const floor = stableVersion(FIRST_ASSET_RELEASE)
+  const releases = []
+  try {
+    const github = await createGitHub()
+    for (let page = 1; ; page++) {
+      const batch = await listConnectReleases(github, OWNER, REPO, DATE_RELEASE_PAGE_SIZE, page)
+      releases.push(...batch)
+      if (batch.length < DATE_RELEASE_PAGE_SIZE) break
+      // Newest first: past the first release older than the asset, no
+      // release can have it.
+      if (batch.some((r) => r && stableVersion(r.tag_name) && compareVersions(stableVersion(r.tag_name), floor) < 0)) break
+    }
+  } catch (error) {
+    logger.warn(`Couldn't list Redpanda Connect releases (${error.message}), so Connect pages keep their git modified dates`)
+    return dates
+  }
+  let newer = releases.find((r) => r && r.tag_name === tag)
+  if (!newer || !newer.published_at) return dates
+  const latest = stableVersion(tag)
+  const older = releases
+    .filter((r) => r && !r.draft && !r.prerelease && stableVersion(r.tag_name) && latest && compareVersions(stableVersion(r.tag_name), latest) < 0)
+    .filter((r) => compareVersions(stableVersion(r.tag_name), floor) >= 0)
+    .filter((r) => (r.assets || []).some((a) => a && a.name === asset.ASSET_NAME))
+    .sort((a, b) => compareVersions(stableVersion(b.tag_name), stableVersion(a.tag_name)))
+    .slice(0, DATE_RELEASE_LIMIT)
+  const pending = new Set(keys)
+  for (const release of older) {
+    let previousFiles
+    try {
+      const archive = await downloadRelease(release.tag_name, logger)
+      if (!archive) throw new Error(`the release lists a ${asset.ASSET_NAME} asset but its download returns 404`)
+      previousFiles = await asset.readTarGz(archive)
+    } catch (error) {
+      // Skipping the release would credit its changes to the newer release,
+      // so stop here: dates found so far are exact, the rest keep git dates.
+      logger.warn(`Couldn't read the Redpanda Connect ${release.tag_name} reference docs to date pages (${error.message}), so ${pending.size} generated files keep their pages' git modified dates`)
+      break
+    }
+    const changed = changedReferenceKeys(files, previousFiles)
+    for (const key of pending) {
+      if (!changed.has(key)) continue
+      if (newer.published_at) dates.set(key, String(newer.published_at).slice(0, 10))
+      pending.delete(key)
+    }
+    if (!pending.size) break
+    files = previousFiles
+    newer = release
+  }
+  return dates
+}
+
+// True when the playbook registers add-git-dates, the only reader of the
+// release dates. Without it, the dating step is skipped.
+function usesGitDates (playbook) {
+  const extensions = (playbook && playbook.antora && playbook.antora.extensions) || []
+  return [].concat(extensions).some((ext) => {
+    const id = typeof ext === 'string' ? ext : ext && ext.enabled !== false ? ext.require || ext.id : null
+    return /(^|[/\\])add-git-dates(\.js)?$/.test(String(id || ''))
+  })
+}
+
 // Adds the generated files to every version of the connect component.
 // Mutates the content catalog and returns what it added, replaced, and
 // skipped. A file another source already provides is skipped, unless
@@ -332,6 +499,8 @@ module.exports.register = function ({ config }) {
   // Set in contextStarted: true when the playbook still lists a connect
   // content source with explicit refs.
   let gitSourceMode = false
+  // Set in contextStarted: true when add-git-dates is in the playbook.
+  let dateReferencePages = false
 
   this.on('contextStarted', ({ playbook }) => {
     // Clear a ref left over from an earlier build in the same process.
@@ -345,6 +514,7 @@ module.exports.register = function ({ config }) {
       )
     }
     gitSourceMode = hasConnectSource(playbook)
+    dateReferencePages = usesGitDates(playbook)
     if (gitSourceMode && (process.env[LOCAL_DIR_ENV] || '').trim()) {
       logger.warn(`${LOCAL_DIR_ENV} is ignored because the playbook lists the connect repo as a content source`)
     }
@@ -356,7 +526,7 @@ module.exports.register = function ({ config }) {
     if (r.kept + r.outsideGenerated + r.providedElsewhere + r.otherComponents === 0) return
     logger.info(
       `Redpanda Connect content: kept ${r.kept} generated files; skipped ${r.providedElsewhere} already provided by another source, ` +
-      `${r.outsideGenerated} outside the generated partials and examples, and ${r.otherComponents} from other components`
+      `${r.outsideGenerated} outside the generated partials, examples, and attachments, and ${r.otherComponents} from other components`
     )
   })
 
@@ -432,9 +602,17 @@ module.exports.register = function ({ config }) {
       (localDir
         ? `replaced ${r.replaced} provided by another source; skipped ${r.outsideGenerated}`
         : `skipped ${r.providedElsewhere} already provided by another source and ${r.outsideGenerated}`) +
-      ' outside the generated partials and examples'
+      ' outside the generated partials, examples, and attachments'
     )
+    // Resolve only included files supplied by this asset. Retained copies
+    // from another source keep their git dates, even if the asset differs.
+    if (!localDir && dateReferencePages) {
+      const keys = new Set(contentCatalog.getPages().flatMap((page) => connectIncludes(page, contentCatalog, origin)))
+      const dates = await referenceReleaseDates(origin.tag, files, keys, logger)
+      const count = markReferenceChanges(contentCatalog, dates, origin)
+      logger.info(`Redpanda Connect ${origin.tag}: resolved last change dates for ${dates.size} included generated files; ${count} pages use those release dates when later than their last commit`)
+    }
   })
 }
 
-module.exports._internal = { isRemote, isUpstreamConnect, redact, isConnectSource, isConnectOrigin, toTag, highestStableTag, stableTags, findOlderReleaseWithAsset, resolveLatestTag, FALLBACK_RELEASE_LIMIT, FALLBACK_PROBE_LIMIT, wantsLatest, removeLatestConnectSources, filterConnectContent, hasConnectSource, addConnectDocs, LOCAL_DIR_ENV }
+module.exports._internal = { isRemote, isUpstreamConnect, redact, isConnectSource, isConnectOrigin, toTag, highestStableTag, stableTags, findOlderReleaseWithAsset, resolveLatestTag, FALLBACK_RELEASE_LIMIT, FALLBACK_PROBE_LIMIT, wantsLatest, removeLatestConnectSources, filterConnectContent, hasConnectSource, addConnectDocs, LOCAL_DIR_ENV, changedReferenceKeys, connectIncludes, markReferenceChanges, usesGitDates, FIRST_ASSET_RELEASE, DATE_RELEASE_LIMIT }

package/extensions/resolve-xrefs-in-attachments.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
+const { escapeHtml } = require('../extension-utils/html-utils')
 
 /**
  * Resolves AsciiDoc xrefs in JSON attachment files to HTML links.
@@ -240,15 +241,3 @@ function resolveXrefsInString (text, contentCatalog, context, logger) {
     }
   })
 }
-
-/**
- * Escape HTML special characters to prevent XSS.
- */
-function escapeHtml (text) {
-  if (!text) return ''
-  return String(text)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-}

package/extensions/util/connect-docs-asset.js

@@ -5,8 +5,9 @@
 // Every connect release (vX.Y.Z, including prereleases) publishes a
 // redpanda-connect-docs.tar.gz asset whose root is `modules/`: the tree that
 // connect's docs generator writes under its docs/ directory. Only
-// modules/components/partials/** and modules/components/examples/** belong to
-// the reference. Releases from before the asset existed answer 404.
+// modules/components/partials/**, modules/components/examples/**, and
+// modules/components/attachments/** (the release's connect-<version>.json)
+// belong to the reference. Releases from before the asset existed answer 404.
 //
 // The same tree can come from a local directory instead (a connect checkout's
 // docs/ after running its generator), or from a local copy of the tarball.
@@ -19,7 +20,7 @@ const OWNER = 'redpanda-data'
 const REPO = 'connect'
 const ASSET_NAME = 'redpanda-connect-docs.tar.gz'
 const MODULE = 'components'
-const FAMILY_DIRS = { partials: 'partial', examples: 'example' }
+const FAMILY_DIRS = { partials: 'partial', examples: 'example', attachments: 'attachment' }
 const DOWNLOAD_ATTEMPTS = 3
 const DOWNLOAD_TIMEOUT_MS = 120000
 
@@ -28,10 +29,10 @@ function assetUrl (tag) {
 }
 
 // The Antora resource of a path inside the tree, or null for anything outside
-// modules/components/partials and modules/components/examples.
+// modules/components/partials, examples, and attachments.
 function toResource (entryPath) {
   const p = String(entryPath || '').replace(/\\/g, '/').replace(/^(\.\/)+/, '')
-  const m = p.match(/^modules\/components\/(partials|examples)\/(.+)$/)
+  const m = p.match(/^modules\/components\/(partials|examples|attachments)\/(.+)$/)
   if (!m || m[2].endsWith('/')) return null
   // A path that climbs out of its directory is not part of the tree.
   if (m[2].split('/').some((segment) => segment === '..' || segment === '')) return null

package/extensions/version-fetcher/fetch-latest-docker-tag.js

@@ -4,30 +4,50 @@
  * The function separates tags into stable (tags not including "-beta") and beta (tags including "-beta"),
  * sorts each group by their major.minor version in descending order, and returns the top tag from each.
  *
+ * It also returns every stable tag it saw (`stableReleases`), so callers can
+ * pick the newest release of an older line, not just the newest overall.
+ * Docker Hub lists the most recently pushed tags first, so the first page
+ * already holds every line that still gets patches. Pass `maxPages` to reach
+ * further back.
+ *
  * @param {string} dockerNamespace - The Docker Hub namespace (organization or username)
  * @param {string} dockerRepo - The repository name on Docker Hub
  * @param {Object} logger - Optional Antora logger instance for logging
- * @returns {Promise<{ latestStableRelease: string|null, latestBetaRelease: string|null }>}
+ * @param {{ maxPages?: number, fetch?: Function }} options - How many pages of 100 tags to read (default 1), and an optional fetch implementation for tests
+ * @returns {Promise<{ latestStableRelease: string|null, latestBetaRelease: string|null, stableReleases: string[] }>}
  */
-module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
-  const { default: fetch } = await import('node-fetch');
+module.exports = async (dockerNamespace, dockerRepo, logger = null, { maxPages = 1, fetch: fetchImpl } = {}) => {
+  const fetch = fetchImpl || (await import('node-fetch')).default;
 
   try {
-    // Fetch a list of tags from Docker Hub.
-    const url = `https://hub.docker.com/v2/repositories/${dockerNamespace}/${dockerRepo}/tags?page_size=100`;
-    const response = await fetch(url);
+    // Fetch a list of tags from Docker Hub. Only the first page is required:
+    // a later page that fails costs older lines, not the latest release.
+    const results = [];
+    let url = `https://hub.docker.com/v2/repositories/${dockerNamespace}/${dockerRepo}/tags?page_size=100`;
+    for (let page = 1; url && page <= maxPages; page++) {
+      const response = await fetch(url);
 
-    if (!response.ok) {
-      throw new Error(`Docker Hub API responded with status ${response.status}`);
-    }
+      if (!response.ok) {
+        const message = `Docker Hub API responded with status ${response.status}`;
+        if (page === 1) throw new Error(message);
+        if (logger) {
+          logger.warn(`${message} for page ${page} of ${dockerRepo} tags; using the first ${results.length} tags.`);
+        } else {
+          console.warn(`${message} for page ${page} of ${dockerRepo} tags; using the first ${results.length} tags.`);
+        }
+        break;
+      }
 
-    const data = await response.json();
+      const data = await response.json();
+      results.push(...(data.results || []));
+      url = data.next;
+    }
 
     // Regex to capture major and minor version numbers (e.g. "v2.3")
     const versionRegex = /^v(\d+)\.(\d+)/;
 
     // Filter tags to include only those matching the version pattern.
-    let tags = data.results.filter(tag => versionRegex.test(tag.name));
+    let tags = results.filter(tag => versionRegex.test(tag.name));
 
     // For specific repositories (e.g. "redpanda-operator"), you might want to filter out certain versions.
     if (dockerRepo === 'redpanda-operator') {
@@ -61,7 +81,8 @@ module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
 
     return {
       latestStableRelease: latestStableReleaseVersion || null,
-      latestBetaRelease: latestBetaReleaseVersion || null
+      latestBetaRelease: latestBetaReleaseVersion || null,
+      stableReleases: sortedStable.map(tag => tag.name)
     };
 
   } catch (error) {
@@ -72,7 +93,8 @@ module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
     }
     return {
       latestStableRelease: null,
-      latestBetaRelease: null
+      latestBetaRelease: null,
+      stableReleases: []
     };
   }
 };

package/extensions/version-fetcher/get-latest-redpanda-helm-version-from-operator.js

@@ -1,7 +1,17 @@
 /**
- * Fetches the latest Helm chart version from the redpanda-operator repository
- * by converting docker tag format v<major>.<minor>.<patch> to release/v<major>.<minor>.x
- * and checking the Chart.yaml file in that branch.
+ * Fetches the latest Helm chart version for an operator release line from the
+ * redpanda-operator repository.
+ *
+ * A stable chart version comes from the newest stable `charts/redpanda/v<major>.<minor>.*`
+ * tag, because a tag marks a chart that was actually published (what
+ * `helm search repo` reports). A release branch's Chart.yaml can be bumped
+ * ahead of the published chart, so it is only the fallback, and the only
+ * source for beta versions.
+ *
+ * The chart has lived at more than one path over time (for example,
+ * `charts/redpanda/Chart.yaml` on release/v25.1.x and
+ * `charts/redpanda/chart/Chart.yaml` from release/v25.2.x on), so the fallback
+ * tries each known path in order.
  *
  * @param {object} github - The GitHub API client.
  * @param {string} owner - The repository owner.
@@ -13,7 +23,50 @@
  */
 module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag, logger = null) => {
   const yaml = require('js-yaml');
-  const path = 'charts/redpanda/chart/Chart.yaml';
+  const semver = require('semver');
+  const chartPaths = ['charts/redpanda/chart/Chart.yaml', 'charts/redpanda/Chart.yaml'];
+  const warn = (message) => (logger ? logger.warn(message) : console.warn(message));
+  const logError = (message) => (logger ? logger.error(message) : console.error(message));
+
+  // Returns the newest stable published chart version of a release line, or
+  // null when the line has no stable chart tag or the lookup fails.
+  const getChartVersionFromTags = async (major, minor) => {
+    if (!github.git?.listMatchingRefs) return null;
+    const tagPrefix = 'charts/redpanda/v';
+    const prefix = `${tagPrefix}${major}.${minor}.`;
+    try {
+      const { data } = await github.git.listMatchingRefs({ owner, repo, ref: `tags/${prefix}` });
+      let newest = null;
+      for (const { ref } of data || []) {
+        const version = semver.valid(String(ref).slice(`refs/tags/${tagPrefix}`.length));
+        if (!version || semver.prerelease(version)) continue;
+        if (semver.major(version) !== Number(major) || semver.minor(version) !== Number(minor)) continue;
+        if (!newest || semver.gt(version, newest)) newest = version;
+      }
+      return newest;
+    } catch (error) {
+      warn(`Could not list ${prefix}* tags in ${owner}/${repo}: ${error.message || error}`);
+      return null;
+    }
+  };
+
+  // Returns the chart version from the first known Chart.yaml path on a
+  // branch, or null when none of the paths exist there.
+  const getChartVersionFromBranch = async (dockerTag, branchName) => {
+    for (const path of chartPaths) {
+      try {
+        const contentResponse = await github.repos.getContent({ owner, repo, path, ref: branchName });
+        const contentDecoded = Buffer.from(contentResponse.data.content, 'base64').toString('utf8');
+        return yaml.load(contentDecoded)?.version || null;
+      } catch (error) {
+        if (error.status === 404) continue;
+        logError(`Failed to fetch ${path} from branch ${branchName}: ${error.message || error}`);
+        return null;
+      }
+    }
+    warn(`Fetched operator ${dockerTag} from Docker Hub but found no Helm chart for it: no ${chartPaths.join(' or ')} on branch ${branchName} (the branch may not exist yet)`);
+    return null;
+  };
 
   /**
    * Helper function to fetch chart version from a branch derived from a docker tag
@@ -38,44 +91,15 @@ module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag, log
         return null;
       }
 
-      const major = versionMatch[1];
-      const minor = versionMatch[2];
-
-      // Convert to release/v<major>.<minor>.x format
-      const branchName = `release/v${major}.${minor}.x`;
-
-      try {
-
-        // Fetch Chart.yaml from the specified branch
-        const contentResponse = await github.repos.getContent({
-          owner,
-          repo,
-          path,
-          ref: branchName,
-        });
+      const [, major, minor] = versionMatch;
+      const isBeta = /-beta/.test(dockerTag);
 
-        const contentBase64 = contentResponse.data.content;
-        const contentDecoded = Buffer.from(contentBase64, 'base64').toString('utf8');
-        const chartYaml = yaml.load(contentDecoded);
-        const version = chartYaml.version || null;
-        return version;
-      } catch (error) {
-        if (error.status === 404) {
-          // Branch doesn't exist yet - this is expected for unreleased versions
-          if (logger) {
-            logger.warn(`Fetched operator ${dockerTag} from Docker Hub but branch ${branchName} not found in GitHub (source may not be released yet)`);
-          } else {
-            console.warn(`Fetched operator ${dockerTag} from Docker Hub but branch ${branchName} not found in GitHub (source may not be released yet)`);
-          }
-        } else {
-          if (logger) {
-            logger.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
-          } else {
-            console.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
-          }
-        }
-        return null;
+      if (!isBeta) {
+        const published = await getChartVersionFromTags(major, minor);
+        if (published) return published;
       }
+
+      return await getChartVersionFromBranch(dockerTag, `release/v${major}.${minor}.x`);
     } catch (error) {
       if (logger) {
         logger.error(`Error processing docker tag ${dockerTag}:`, error.message);

package/extensions/version-fetcher/list-connect-releases.js

@@ -1,10 +1,10 @@
 'use strict'
 
 // The most recent releases of a repository, newest first, as the GitHub API
-// lists them (one page of at most `limit` releases). Each release carries its
+// lists them (the requested page of at most `limit` releases). Each release carries its
 // assets, so a caller can check for an asset without downloading it. Throws
 // when the API is unavailable, so the caller can fall back to git tags.
-module.exports = async (github, owner, repo, limit) => {
-  const { data } = await github.rest.repos.listReleases({ owner, repo, per_page: limit })
+module.exports = async (github, owner, repo, limit, page = 1) => {
+  const { data } = await github.rest.repos.listReleases({ owner, repo, per_page: limit, page })
   return Array.isArray(data) ? data.slice(0, limit) : []
 }

package/extensions/version-fetcher/release-lines.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// Helpers for pinning an attribute to the release line a component version
+// documents, rather than to the newest release overall. The lines come from
+// the fetched release tags themselves, so a new release line is picked up as
+// soon as it ships and nothing needs a manual version map.
+
+const semver = require('semver');
+
+/**
+ * Returns the newest stable tag of each major.minor release line.
+ *
+ * Only plain `v<major>.<minor>.<patch>` tags count. Prereleases are skipped,
+ * and so are the legacy operator tags such as `v2.3.15-24.3.18`, whose suffix
+ * semver reads as a prerelease. Patches are compared as semver, so the result
+ * does not depend on the order the registry lists tags in.
+ *
+ * @param {string[]} tags - Release tags, for example ['v26.1.12', 'v26.1.9'].
+ * @returns {Map<string, string>} Release line (for example '26.1') to its newest tag.
+ */
+function latestStablePerLine (tags) {
+  const lines = new Map();
+  for (const tag of tags || []) {
+    if (typeof tag !== 'string' || !tag.startsWith('v')) continue;
+    const parsed = semver.parse(tag.slice(1));
+    if (!parsed || parsed.prerelease.length || parsed.build.length) continue;
+    const line = `${parsed.major}.${parsed.minor}`;
+    const current = lines.get(line);
+    if (!current || semver.gt(parsed, current.slice(1))) lines.set(line, tag);
+  }
+  return lines;
+}
+
+/**
+ * Returns the release line an Antora component version names, or null when
+ * the version is not a `major.minor` pair (for example, an unversioned
+ * component or a version named after something other than a release).
+ *
+ * @param {string|null|undefined} version - The component version, for example '25.3'.
+ * @returns {string|null}
+ */
+function releaseLineOf (version) {
+  const match = /^(\d+)\.(\d+)$/.exec(String(version ?? ''));
+  return match ? `${Number(match[1])}.${Number(match[2])}` : null;
+}
+
+/**
+ * Returns true when a component version documents an older release line than
+ * the component's latest version. Only those versions are pinned to their own
+ * line. The latest version, prereleases ahead of it, and unversioned
+ * components keep the newest release overall.
+ *
+ * @param {string} version - The component version.
+ * @param {string} latestVersion - The component's latest version.
+ * @returns {boolean}
+ */
+function isOlderReleaseLine (version, latestVersion) {
+  const line = releaseLineOf(version);
+  const latestLine = releaseLineOf(latestVersion);
+  if (!line || !latestLine) return false;
+  return semver.lt(`${line}.0`, `${latestLine}.0`);
+}
+
+module.exports = { latestStablePerLine, releaseLineOf, isOlderReleaseLine };