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

package/extension-utils/html-utils.js

@@ -0,0 +1,27 @@
+'use strict'
+
+/**
+ * Shared HTML utility functions for extensions and macros.
+ */
+
+/**
+ * Escape a value for safe inclusion in HTML text or inside a double-quoted
+ * attribute. Escaping `&` first is what keeps the result idempotent-safe for a
+ * single pass; escaping `"` is what stops an author-supplied string from ending
+ * the attribute it sits in.
+ *
+ * @param {*} value - Value to escape. `null` and `undefined` become ''.
+ * @returns {string} The escaped string.
+ */
+function escapeHtml (value) {
+  if (value === null || value === undefined) return ''
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+module.exports = {
+  escapeHtml,
+}

package/extensions/REFERENCE.adoc

@@ -404,39 +404,76 @@ You can optionally display pages only if they match the component and version of
 
 == Redpanda Connect tag modifier
 
-This extension sources the Redpanda Connect reference partials (field reference, examples, metadata, descriptions, config snippets, and the Bloblang reference) from the `docs/` directory of the connect repository, at the latest Connect release.
+This extension adds the Redpanda Connect generated reference docs (field reference, examples, metadata, descriptions, config snippets, the Bloblang reference, and `platforms/catalog.json`) to the `connect` component that rp-connect-docs provides, from a Connect release.
 
-Add the connect repository as a content source next to rp-connect-docs:
+Every Connect release publishes the generated tree as a release asset named `redpanda-connect-docs.tar.gz`, at `\https://github.com/redpanda-data/connect/releases/download/<tag>/redpanda-connect-docs.tar.gz`. The playbook does not list the connect repository as a content source. If it still lists the upstream repository with `tags: latest`, the extension removes that source. See <<Playbooks that list the connect repository>>.
+
+At build time, when the playbook has the `connect` component, the extension:
+
+. Picks the release: the latest stable `vX.Y.Z` release by default, so the site never shows fields from unreleased code on connect's `main` branch. It asks the GitHub API for the latest release and falls back to the highest stable `vX.Y.Z` tag from `git ls-remote`. If neither works, the build stops with an error. The `tag` option picks a specific release instead.
+. Downloads that release's `redpanda-connect-docs.tar.gz` asset. With a GitHub token it downloads through the releases API, which keeps working if the connect repository becomes private. Without one, or if GitHub rejects the token, it uses the public download URL.
+. Adds `modules/components/partials/**` as partials, `modules/components/examples/**` as examples, and `modules/components/attachments/**` (the release's `connect-<version>.json`, read by the Bloblang playground) as attachments of the `components` module, in every version of the `connect` component. A file that another source, such as rp-connect-docs, already provides is skipped and counted in the log, so rp-connect-docs can keep committing its own copies until it stops.
+. When the playbook also registers `add-git-dates`, dates each page by the Connect release that last changed its reference. For every generated partial or example a page includes, directly or through another generated partial such as `bloblang/methods.adoc`, the extension compares the release with older releases that have the asset, newest first, and takes the publish date of the newest release that changed the file. A page that single-sources such a connect page, such as a Cloud stub, gets the same date. `add-git-dates` uses the date as `page-git-modified-date` when it is later than the page's last commit. The walk stops at v4.113.0, the first release with the asset, and after at most 10 older releases. A file that is unchanged for the whole walk keeps the page's git date. If the releases listing or an older release's download fails, the extension logs a warning and pages keep their git dates, so the build never stops for a date. Without `add-git-dates` in the playbook, the extension skips this step and downloads only the release it uses.
+
+A release from before the asset existed has none, and the download returns 404. A new release can also be missing it for a while: Connect publishes the release first and attaches the asset 15 to 20 minutes later in a separate job, which can fail.
+
+So when the latest release has no asset, the extension falls back to the newest older stable `vX.Y.Z` release that has one, and logs a warning that names both, such as `Redpanda Connect v4.114.0 has no redpanda-connect-docs.tar.gz asset yet; using v4.113.0`. It reads the asset lists of the 10 most recent releases from the GitHub releases API, so it downloads only the release it picks. If the API is unavailable, it tries the downloads of the next 3 lower stable tags from `git ls-remote` instead. A release picked with the `tag` option never falls back: if it has no asset, the build stops with an error that names the release.
+
+When no release it checks has the asset, the extension logs this and adds nothing. The `generate-rp-connect-info` extension then stops the build if connector pages are missing any generated set they include: the `fields/`, `descriptions/`, or `availability/` partials, or the `common/` or `advanced/` examples. This also catches an incomplete asset, which would otherwise publish pages with unresolved includes. Any other failure, such as a network error or a corrupt archive, stops the build, because building without the reference would publish connector pages with no fields.
+
+The extension shares the release it used, including a fallback release, so `generate-rp-connect-info` reads `catalog.json` and `info.csv` for the same release as the reference docs. It adds its files before any other `contentClassified` listener runs, wherever it is listed in the playbook.
+
+=== Preview unreleased Connect changes
+
+To build with reference docs that are not released yet, generate them in a connect checkout and point `REDPANDA_CONNECT_DOCS_DIR` at the result:
+
+[,bash]
+----
+export REDPANDA_CONNECT_DOCS_DIR=/path/to/connect/docs
+npx antora --fetch local-antora-playbook.yml
+----
+
+The value is a directory that contains `modules/` (a connect checkout's `docs/` directory after running its docs generator, or the checkout root), or a local copy of a `redpanda-connect-docs.tar.gz` file. It wins over the `tag` option and the latest release, and nothing is downloaded. Its files also replace any copy another source provides, such as the copies rp-connect-docs commits, and the log counts how many were replaced. Set `tag` as well to choose the release that `generate-rp-connect-info` reads `info.csv` from.
+
+=== Playbooks that list the connect repository
+
+Before the release asset, playbooks listed the connect repository as a content source:
 
 ```yaml
 content:
   sources:
   - url: https://github.com/redpanda-data/connect
-    tags: latest # replaced with the latest release tag at build time
+    tags: latest
     start_path: docs
 ```
 
-At build time the extension:
+Connect releases no longer include `docs/antora.yml`, so Antora cannot aggregate that source. When the upstream `redpanda-data/connect` repository is listed with `tags: latest` as its only ref, the extension removes the source from the playbook before Antora fetches content, logs a warning that it is no longer needed, and uses the release asset. Remove the source from the playbook to silence the warning.
 
-* Pins a source that sets `tags: latest` to the latest Connect release tag and clears its branches (a source with any other refs, such as a PR branch for a preview, is left as configured), so the site never shows fields from unreleased code on connect's `main` branch. It asks the GitHub API for the latest release and falls back to the highest stable `vX.Y.Z` tag from `git ls-remote`. If neither works, the build stops with an error.
-* Keeps only the `modules/components/partials/` and `modules/components/examples/` files of the `connect` component from that source. Any file that another source, such as rp-connect-docs, already provides is skipped, and so is content from older Connect tags that name their component `redpanda-connect`. Antora fails the build on a duplicate page or partial, so you can add the source to a playbook before or after rp-connect-docs stops committing its own generated copies.
+A connect source with explicit refs is kept, which is how you preview a connect branch: a branch, a specific tag, a fork, or a local clone whose directory is named `connect`. In that case the extension downloads no asset, and:
 
-A local clone whose directory is named `connect` is filtered the same way but not pinned, so a local playbook can use `branches: HEAD` to test uncommitted changes.
+* Only the `modules/components/partials/` and `modules/components/examples/` files of the `connect` component are kept from that source. Any file that another source already provides is skipped, and so is content from older Connect tags that name their component `redpanda-connect`.
+* `REDPANDA_CONNECT_DOCS_DIR` and the `tag` option are ignored.
+* The ref must have `docs/antora.yml` and the generated docs. If the generated sets are missing, the `generate-rp-connect-info` error names the connect source.
 
 === Environment variables
 
-- `REDPANDA_GITHUB_TOKEN` (optional): A GitHub token for the release lookup. Without it, the extension sends unauthenticated API requests, which GitHub can rate limit. The `git ls-remote` fallback needs no token.
+- `REDPANDA_CONNECT_DOCS_DIR` (optional): A local directory, or a local `redpanda-connect-docs.tar.gz` file, to read the reference docs from instead of a release. See <<Preview unreleased Connect changes>>.
+- `REDPANDA_GITHUB_TOKEN` (optional): A GitHub token for the latest release lookup, the fallback release listing, the asset download, and the `git ls-remote` fallback. The extension also reads `ACTIONS_BOT_TOKEN`, `GITHUB_TOKEN`, `VBOT_GITHUB_API_TOKEN`, `GH_TOKEN`, and a github.com entry in `GIT_CREDENTIALS`, in that order. Without any GitHub token, the extension sends unauthenticated requests, which GitHub can rate limit, and which only work while the connect repository is public.
 
 === Configuration options
 
-There are no configurable options for this extension.
+`tag` (optional):: A Connect release tag, such as `v4.113.0`, to use instead of the latest stable release. A missing `v` prefix is added. If that release has no asset, the build stops: an explicit tag never falls back to an older release. `latest` is rejected, because the latest release is the default without `tag`. Ignored when the playbook keeps a connect content source with explicit refs.
 
 === Registration
 
+Register this extension together with `generate-rp-connect-info`:
+
 ```yaml
 antora:
   extensions:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/modify-connect-tag-playbook'
+      # tag: v4.113.0 # optional: a specific release instead of the latest
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-info'
 ```
 
 == Version fetcher
@@ -454,8 +491,8 @@ The following attributes are available to all versions of all Antora components:
 `console-beta-version`:: The latest beta version of Redpanda Console.
 `operator-beta-version`:: The latest beta version of the Redpanda Operator.
 `helm-beta-version`:: The latest beta version of the Redpanda Helm chart.
-`latest-operator-version`:: The latest release version of the Redpanda Operator. This value keeps its `v` prefix (for example, `v25.1.3`) because pages pass it straight to `helm --version`.
-`latest-redpanda-helm-chart-version`:: The latest release version of the Redpanda Helm chart.
+`latest-operator-version`:: The latest release version of the Redpanda Operator for the component version's release line (see <<operator-and-chart-per-version>>). This value keeps its `v` prefix (for example, `v25.1.3`) because pages pass it straight to `helm --version`.
+`latest-redpanda-helm-chart-version`:: The latest release version of the Redpanda Helm chart for the component version's release line (see <<operator-and-chart-per-version>>). This value has no `v` prefix (for example, `25.3.11`).
 
 The following attributes are available to the latest version of each Antora component:
 
@@ -475,6 +512,19 @@ ever moves forwards.
 
 A short attribute is only set when a `major.minor` pair can be derived. Release channels that are not versions, such as `nightly` or `latest`, get a `-version` and a `-tag` but no `-version-short`, so a page never renders a fabricated release line.
 
+[[operator-and-chart-per-version]]
+==== Operator and Helm chart versions per component version
+
+An operator or Helm chart release supports its own Redpanda version and one minor version above and below it, so each component version gets the release of its own line:
+
+* A component version named `<major>.<minor>` that is older than the component's latest version gets the newest stable release in that line. For example, version `25.3` gets the newest `v25.3.x` operator and the newest `25.3.x` chart, even when a `26.2.x` release exists.
+* The component's latest version, any prerelease version ahead of it, and unversioned components get the newest stable release overall.
+* If an older line has no stable operator release (for example, lines that shipped only legacy `v2.x.y-<redpanda-version>` operator tags), the newest release does not support it, so both attributes keep the values the component version's `antora.yml` sets. If the line has an operator release but no chart release, only the chart attribute keeps its `antora.yml` value. An attribute that `antora.yml` leaves unset or empty falls back to the newest release overall. Either way, the build logs a warning that names the line.
+
+The release lines come from the fetched operator tags, so no version map needs updating when a line ships. The extension reads up to three pages (300 tags) of the operator's Docker Hub tags, newest pushes first.
+
+The chart version of a line is the newest stable `charts/redpanda/v<major>.<minor>.*` tag in the redpanda-operator repository, which marks a published chart (what `helm search repo` reports). A release branch's `Chart.yaml` can be ahead of the published chart, so the extension reads it only when the line has no chart tag, trying each path the chart has used in order: `charts/redpanda/chart/Chart.yaml`, then `charts/redpanda/Chart.yaml` (the layout of `release/v25.1.x`).
+
 ==== Seed a fallback in antora.yml
 
 Every attribute here depends on a successful GitHub lookup at build time. If a lookup fails, for example because of a rate limit or a missing token, the attribute is never set and any page that references it renders the attribute name in braces.
@@ -842,6 +892,8 @@ The extension accepts the following configuration options:
 
 termspath (optional):: Specifies the path to a local directory containing term files (in `.adoc` format). If this path is provided, the extension will attempt to load terms from this directory first. If this path is not provided or no valid terms are found in the specified directory, the extension will fall back to loading terms from the `shared` component.
 
+glossarypage (optional):: The resource ID of one page that holds the glossary for the whole site, such as `home:ROOT:glossary.adoc`. The extension appends every term to that page and sets every component's `glossary-page` attribute to it, so `glossterm` links from any component point at the one glossary. Any `reference:glossary.adoc` pages that components still have are filled too, so they stay complete until they are removed. If the page does not exist, the extension logs a warning and links each component to its own `reference:glossary.adoc`, as without this option. When the page exists, it takes precedence over a `glossary-page` attribute set in a component's `antora.yml`, so a per-component value only applies if this page is missing.
+
 Term files should follow the following structure:
 
 ```asciidoc
@@ -1077,7 +1129,7 @@ This extension adds accurate git-based created and modified dates to documentati
 The extension adds the following attributes to each page:
 
 - `page-git-created-date`: The date when the file was first committed (YYYY-MM-DD format)
-- `page-git-modified-date`: The date when the file was last modified (YYYY-MM-DD format)
+- `page-git-modified-date`: The date when the file was last modified (YYYY-MM-DD format). For a page with Connect reference content, this is the date of the most recent Connect release that changed that content, when it is later than the page's last commit (see <<Redpanda Connect tag modifier>>).
 
 These attributes are available for use in UI templates (for metadata, display banners, etc.) and are exported to markdown files for AI consumption.
 

package/extensions/add-git-dates.js

@@ -180,6 +180,16 @@ async function getTreeFiles (git, gitdir, oid, prefix, cache, treeCache) {
   return files
 }
 
+// The later of two YYYY-MM-DD dates. modify-connect-tag-playbook sets
+// page.connectReferenceModified to the date of the Connect release that last
+// changed a page's generated reference, which lives in a release asset and so
+// in no git commit of the page's repo.
+function laterDate (a, b) {
+  if (!b) return a
+  if (!a) return b
+  return b > a ? b : a
+}
+
 module.exports.register = function () {
   raiseListenerLimit(this)
   const logger = this.getLogger('add-git-dates-extension')
@@ -271,7 +281,7 @@ module.exports.register = function () {
           const dates = fileDateMap.get(relativeFilePath)
           if (dates) {
             page.asciidoc.attributes['page-git-created-date'] = dates.created
-            page.asciidoc.attributes['page-git-modified-date'] = dates.modified
+            page.asciidoc.attributes['page-git-modified-date'] = laterDate(dates.modified, page.connectReferenceModified)
             processedCount++
           }
         }
@@ -288,3 +298,5 @@ module.exports.register = function () {
     logger.info(`Git dates added: processed=${processedCount}, skipped=${skippedCount}, duration=${duration}ms (${perPage}ms/page)`)
   })
 }
+
+module.exports._internal = Object.assign(module.exports._internal || {}, { laterDate })

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/generate-rp-connect-info.js

@@ -13,29 +13,81 @@ const DEFAULTS = {
   githubRepo: 'connect'
 }
 
-// Connector pages include the generated field reference from the connect repo
-// (see the modify-connect-tag-playbook extension). If a playbook has the
-// Connect pages but none of those partials, every connector page would publish
-// without its fields, and Antora only logs the missing includes. Fail the
-// build instead so the playbook gets fixed before anything is published.
-function assertConnectReferencePresent (contentCatalog) {
+// Generated sets that connector pages include, by Antora family. Each one
+// must be present, or pages publish with unresolved includes.
+// The generated partial and example directories that connector pages include,
+// read from the pages themselves, so the guard asks for exactly what the pages
+// in this build use (rp-connect-docs pages gain availability includes, for
+// example, when they move to the generated docs).
+const PARTIAL_INCLUDE = /include::connect:components:partial\$([a-z0-9_-]+)\//g
+const EXAMPLE_INCLUDE = /include::(?:connect:)?components:example\$([a-z0-9_-]+)\//g
+
+function includedDirs (pages) {
+  const partial = new Set()
+  const example = new Set()
+  for (const page of pages) {
+    const text = page.contents ? page.contents.toString() : ''
+    for (const m of text.matchAll(PARTIAL_INCLUDE)) partial.add(m[1])
+    for (const m of text.matchAll(EXAMPLE_INCLUDE)) example.add(m[1])
+  }
+  // Name the core sets first, in a fixed order, so the error reads the same
+  // way every time.
+  const order = ['fields', 'descriptions', 'availability', 'metadata', 'examples', 'common', 'advanced']
+  const rank = (d) => (order.includes(d) ? order.indexOf(d) : order.length)
+  const sorted = (set) => [...set].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+  return { partial: sorted(partial), example: sorted(example) }
+}
+
+// Connector pages include the generated field reference, description meta,
+// availability, and config examples, which the modify-connect-tag-playbook
+// extension adds from the redpanda-connect-docs.tar.gz asset of a connect
+// release. If a playbook has the Connect pages but any set is missing (an
+// incomplete asset, or a connect source whose ref lacks them), connector
+// pages would publish with unresolved includes, and Antora only logs them.
+// Fail the build instead so the playbook gets fixed before anything is
+// published.
+//
+// `connectSources` are the connect content sources still in the playbook,
+// which means no release asset was downloaded.
+function assertConnectReferencePresent (contentCatalog, { connectSources = [] } = {}) {
   const component = contentCatalog.getComponents().find((c) => c.name === 'connect')
   if (!component) return
-  // Only connector pages (inputs/kafka.adoc and so on) include field
-  // partials. Overview pages at the module root don't.
+  // Only connector pages (inputs/kafka.adoc and so on) include the generated
+  // sets. Overview pages at the module root don't.
   const pages = contentCatalog.findBy({ component: 'connect', module: 'components', family: 'page' })
     .filter((p) => p.src.relative.includes('/'))
   if (!pages.length) return
-  const fields = contentCatalog.findBy({ component: 'connect', module: 'components', family: 'partial' })
-    .filter((f) => f.src.relative.startsWith('fields/'))
-  if (fields.length) return
+  const missingIn = (family, dirs) => {
+    const files = contentCatalog.findBy({ component: 'connect', module: 'components', family })
+    return dirs.filter((dir) => !files.some((f) => f.src.relative.startsWith(`${dir}/`)))
+      .map((dir) => `components:${family}$${dir}/*`)
+  }
+  const wanted = includedDirs(pages)
+  const missing = [...missingIn('partial', wanted.partial), ...missingIn('example', wanted.example)]
+  if (!missing.length) return
+  const sourceHint = connectSources.length
+    ? `The playbook lists a connect content source (${connectSources.join(', ')}), so no release asset was downloaded and these files must come from that source's refs. ` +
+      'Point it at a ref that has the generated docs, or remove it to use the release asset. '
+    : ''
   throw new Error(
-    'The connect component has connector pages but no generated field partials (components:partial$fields/*). ' +
-    'Add the connect repository as a content source (url: https://github.com/redpanda-data/connect, tags: latest, start_path: docs) ' +
-    'and register the modify-connect-tag-playbook extension, or check that the latest Connect release includes docs/modules/components.'
+    `The connect component has connector pages but no generated ${missing.join(' or ')} files. ` +
+    sourceHint +
+    'These come from the redpanda-connect-docs.tar.gz asset of a Redpanda Connect release, which the ' +
+    'modify-connect-tag-playbook extension downloads. Register that extension and check its log: ' +
+    'the release it used (the latest stable release, or the one in its `tag` config) may have no asset or an incomplete one. ' +
+    'Set `tag` to a release that has the asset, or set REDPANDA_CONNECT_DOCS_DIR to a local directory that contains ' +
+    'modules/ (for example a connect checkout\'s docs/ after running its docs generator).'
   )
 }
 
+// The connect content sources in a playbook, with credentials removed.
+function connectSourcesOf (playbook) {
+  const sources = (playbook && playbook.content && playbook.content.sources) || []
+  return sources
+    .filter((s) => catalogUtil.isConnectSource(s.url))
+    .map((s) => String(s.url).replace(/([a-z][a-z+.-]*:\/\/)[^@/\s]*@/gi, '$1'))
+}
+
 module.exports.assertConnectReferencePresent = assertConnectReferencePresent
 
 module.exports.register = function ({ config }) {
@@ -63,8 +115,8 @@ module.exports.register = function ({ config }) {
   let translatedRows = null
 
   // Use 'on' and return the promise so Antora waits for async completion
-  this.on('contentClassified', ({ contentCatalog }) => {
-    assertConnectReferencePresent(contentCatalog)
+  this.on('contentClassified', ({ contentCatalog, playbook }) => {
+    assertConnectReferencePresent(contentCatalog, { connectSources: connectSourcesOf(playbook) })
     return processContent(contentCatalog)
   })
 
@@ -132,8 +184,9 @@ module.exports.register = function ({ config }) {
 
   // Raw catalog rows (info.csv column names) for this build.
   //
-  // The generated partials/platforms/catalog.json from the connect content
-  // source comes first: it is pinned to the same ref as the reference content
+  // The generated partials/platforms/catalog.json from connect (the release
+  // asset, or a connect content source) comes first: it is from the same ref
+  // as the reference content
   // and carries status, categories, and cgo data that info.csv lacks. info.csv
   // still supplies the SQL driver rows, which are not components and so are
   // not in the catalog. Without catalog.json, info.csv supplies every row.
@@ -152,7 +205,8 @@ module.exports.register = function ({ config }) {
     let csvRows = []
     try {
       const csvText = await fetchCSV(localCsvPath, contentCatalog)
-      csvRows = Papa.parse(csvText, { header: true, skipEmptyLines: true }).data
+      // connect's info.csv pads every column with spaces, headers included
+      csvRows = Papa.parse(csvText, { header: true, skipEmptyLines: true, transformHeader: (h) => h.trim() }).data
     } catch (error) {
       if (!catalogRows) throw error
       logger.warn(`Could not fetch info.csv for the SQL driver rows, so the SQL driver support list is empty: ${error.message}`)
@@ -186,8 +240,9 @@ module.exports.register = function ({ config }) {
   }
 
   // The ref to read info.csv from, in order:
-  // 1. the tag modify-connect-tag-playbook resolved for the connect content source
-  // 2. the ref of the connect content source in the content catalog
+  // 1. the tag modify-connect-tag-playbook resolved (for the release asset or
+  //    the connect content source)
+  // 2. the ref of the connect files in the content catalog
   // 3. latest-connect-version in antora.yml in the working directory
   // 4. main, with a warning, because the catalog can then disagree with the
   //    reference content
@@ -201,9 +256,9 @@ module.exports.register = function ({ config }) {
     const normalizedVersion = connectVersion ? String(connectVersion).trim().replace(/^v/, '') : ''
     if (normalizedVersion) return { ...base, ref: `v${normalizedVersion}`, source: 'latest-connect-version in antora.yml' }
     logger.warn(
-      'No connect content source or latest-connect-version found, so info.csv is read from connect main. ' +
-      'Catalog badges can then disagree with the reference content. Add the connect content source and the ' +
-      'modify-connect-tag-playbook extension to the playbook.'
+      'No resolved connect release or latest-connect-version found, so info.csv is read from connect main. ' +
+      'Catalog badges can then disagree with the reference content. Register the modify-connect-tag-playbook ' +
+      'extension, or set its `tag` config when REDPANDA_CONNECT_DOCS_DIR is set.'
     )
     return { ...base, ref: 'main', source: 'fallback' }
   }