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

package/bin/doc-tools-mcp.js

@@ -10,7 +10,6 @@
  * - Context-aware: Works from any repository based on cwd
  * - Antora intelligence: Understands component/module structure
  * - Automation: Run doc-tools generate commands
- * - Auto-discovery: Prompts loaded automatically from mcp/prompts/
  * - Validation: Startup checks ensure all resources are accessible
  * - Telemetry: Usage tracking for adoption metrics
  */
@@ -201,7 +200,7 @@ const tools = [
   },
   {
     name: 'generate_rpcn_connector_docs',
-    description: 'Generate Redpanda Connect connector documentation. Creates component documentation for all connectors. Writers use this when updating connector reference docs. Automatically uses docs-data/overrides.json if present.',
+    description: 'Generate Redpanda Connect connector documentation. Creates component documentation for all connectors. Writers use this when updating connector reference docs. Field, component, and Bloblang descriptions come from the component specs in redpanda-data/connect and redpanda-data/benthos, so fix wrong text with a PR there.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -239,7 +238,7 @@ const tools = [
         },
         overrides: {
           type: 'string',
-          description: 'Path to optional JSON file with overrides (defaults to docs-data/overrides.json if present)'
+          description: 'Path to an optional JSON file of description overrides (optional). Nothing is merged unless you pass it.'
         },
         cloud_version: {
           type: 'string',
@@ -516,7 +515,7 @@ const tools = [
         surface: {
           type: 'string',
           description: 'Override surface to audit (optional, defaults to "properties")',
-          enum: ['properties', 'rpk', 'connect']
+          enum: ['properties', 'rpk']
         },
         output: {
           type: 'string',
@@ -594,7 +593,7 @@ const resourceMap = {
 
 /**
  * Load resource content from team-standards directory
- * @param {string} uri - Resource URI (such as 'redpanda://style-guide')
+ * @param {string} uri - Resource URI (such as 'redpanda://personas')
  * @returns {Object} Resource content
  */
 function getResourceContent(uri) {

package/bin/doc-tools.js

@@ -896,7 +896,7 @@ automation
   .option('--template-metadata <path>', 'Metadata section partial template', path.resolve(__dirname, '../tools/redpanda-connect/templates/metadata-partials.hbs'))
   .option('--template-description <path>', 'Description section partial template', path.resolve(__dirname, '../tools/redpanda-connect/templates/descriptions-partials.hbs'))
   .option('--template-bloblang <path>', 'Custom Handlebars template for bloblang function/method partials')
-  .option('--overrides <path>', 'Optional JSON file with overrides', 'docs-data/overrides.json')
+  .option('--overrides <path>', 'Optional JSON file of description overrides to merge into the generated output. Nothing is merged unless you pass it. Connector descriptions come from the connect and benthos component specs, so fix wrong text there')
   .option('--include-bloblang', 'Include Bloblang functions and methods in generation')
   .option('--no-partials', 'Skip the generated partials, config snippets, and Bloblang reference because the connect repo publishes them. What\'s new, diffs, drafts, nav, and the version bump still run')
   .option('--prune-orphaned-descriptions', 'Allow the description-partial orphan sweep to blank more than 10% of the tree. Only use this when the connector dataset is confirmed complete: an incomplete dataset looks identical to a mass upstream deletion and the sweep blanks published content')
@@ -2881,6 +2881,43 @@ programCli
     runCli(options)
   })
 
+/**
+ * doc-impact-recording
+ *
+ * @description
+ * Extracts every redpanda-docs MCP call and its result from a Claude Code
+ * transcript (the claude-code-action execution file, or `claude -p
+ * --output-format stream-json` output) and writes them as a doc-impact eval
+ * recording. Only the tool name, arguments and result content are kept.
+ * Writes nothing when the session made no docs calls.
+ *
+ * @why
+ * The doc-impact eval replays docs answers per PR. Answers recorded later
+ * come from docs that may already contain the writer's fix, so the eval
+ * would score a correct "already documented" as a miss. The doc-strings
+ * review saves what the docs server told it at review time, and the eval
+ * miner turns that into the item's recording.
+ *
+ * @example
+ * # What the doc-strings review runs after its Claude step
+ * npx doc-tools doc-impact-recording --execution-file "$RUNNER_TEMP/claude-execution-output.json" \
+ *   --output recording.json --item redpanda-operator-1615 --server-url https://docs.redpanda.com/mcp
+ */
+programCli
+  .command('doc-impact-recording')
+  .description('Extract the docs MCP calls from a Claude Code transcript into a doc-impact eval recording')
+  .requiredOption('--execution-file <path>', 'Transcript: a JSON array of SDK messages or stream-json lines')
+  .requiredOption('--output <path>', 'Recording file to write (not written when there are no docs calls)')
+  .option('--item <id>', 'Item id to store in the recording')
+  .option('--server <name>', 'MCP server name in the transcript tool names', 'redpanda-docs')
+  .option('--server-url <url>', 'URL of that MCP server, stored in the recording')
+  .option('--model <name>', 'Model to store (default: the model in the transcript init message)')
+  .option('--recorded-at <iso>', 'Timestamp to store (default: now)')
+  .action((options) => {
+    const { runCli } = require('../tools/doc-impact-recording')
+    process.exit(runCli(options))
+  })
+
 /**
  * lint-screenshots
  *
@@ -3136,7 +3173,7 @@ overridesGroup
   .description('Classify each override field as redundant, upstreamable, or keep against extracted source strings')
   .requiredOption('--overrides <path>', 'Path to the overrides JSON file (for example docs-data/property-overrides.json)')
   .option('--extracted <path>', 'Path to the extracted source JSON (property extractor raw output; required for the properties surface)')
-  .addOption(new Option('--surface <surface>', 'Override surface to audit').choices(['properties', 'rpk', 'connect']).default('properties'))
+  .addOption(new Option('--surface <surface>', 'Override surface to audit').choices(['properties', 'rpk']).default('properties'))
   .addOption(new Option('--format <format>', 'Output format').choices(['json', 'human']).default('json'))
   .option('--repo <path>', 'Redpanda checkout to extract raw source strings from (alternative to --extracted)')
   .option('--output <path>', 'Also write the JSON result to this file')

package/bin/mcp-tools/generated-docs-review.js

@@ -189,7 +189,7 @@ function generateReviewReport(results, outputPath) {
         report += `. Regenerate docs\n\n`;
       } else if (issue.issue.includes('Invalid $ref')) {
         report += `*Action:*\n\n`;
-        report += `. Open \`docs-data/overrides.json\`\n`;
+        report += `. Open \`${issue.file}\`\n`;
         report += `. Find the reference at \`${issue.path}\`\n`;
         report += `. Either add the missing definition or fix the reference\n`;
         report += `. Regenerate docs\n\n`;
@@ -273,6 +273,17 @@ function generateReviewReport(results, outputPath) {
   return report;
 }
 
+/**
+ * Where to fix Redpanda Connect reference text. The connect repo generates
+ * the field, component, and Bloblang partials from its specs and the benthos
+ * specs, and each Connect release publishes them for the docs build.
+ */
+const RPCN_SOURCE_GUIDANCE =
+  'Connector field, component, and Bloblang descriptions are generated from the component specs in ' +
+  'redpanda-data/connect and redpanda-data/benthos. To fix wrong or missing text, open a PR against ' +
+  'the spec in that repository; the fix ships in the next Connect release. Edit hand-written page ' +
+  'prose in rp-connect-docs.';
+
 /**
  * Review generated documentation for quality issues
  * @param {Object} args - Arguments
@@ -282,7 +293,7 @@ function generateReviewReport(results, outputPath) {
  * @param {string} [args.properties_dir] - Custom path to properties directory (default: modules/reference)
  * @param {string} [args.metrics_file] - Custom path to metrics file (default: modules/reference/pages/public-metrics-reference.adoc)
  * @param {string} [args.rpk_dir] - Custom path to RPK docs directory (default: autogenerated/{version}/rpk)
- * @param {string} [args.overrides_file] - Custom path to overrides.json for RPCN connectors (default: docs-data/overrides.json)
+ * @param {string} [args.overrides_file] - Optional connector overrides file to validate for RPCN connectors. Without it, the review points at the connect and benthos specs, where connector descriptions live
  * @returns {Object} Review results with issues and suggestions
  */
 function reviewGeneratedDocs(args) {
@@ -524,16 +535,21 @@ function reviewGeneratedDocs(args) {
       }
 
       case 'rpcn_connectors': {
-        // Read overrides.json (use custom path or default)
-        const overridesPath = args.overrides_file ?
-          path.join(repoRoot.root, args.overrides_file) :
-          path.join(repoRoot.root, 'docs-data', 'overrides.json');
+        // Connector field, component, and Bloblang descriptions are generated
+        // from the connect and benthos specs, so there is no overrides file to
+        // check by default. Only an overrides file passed explicitly is validated.
+        if (!args.overrides_file) {
+          suggestions.push(RPCN_SOURCE_GUIDANCE);
+          break;
+        }
+
+        const overridesPath = path.join(repoRoot.root, args.overrides_file);
 
         if (!fs.existsSync(overridesPath)) {
           return {
             success: false,
-            error: `overrides.json not found at ${overridesPath}`,
-            suggestion: 'Generate RPCN connector docs first using generate_rpcn_connector_docs tool, or specify custom path with overrides_file parameter'
+            error: `Overrides file not found at ${overridesPath}`,
+            suggestion: `Check the overrides_file path, or omit it. ${RPCN_SOURCE_GUIDANCE}`
           };
         }
 
@@ -736,5 +752,6 @@ function reviewGeneratedDocs(args) {
 
 module.exports = {
   generateReviewReport,
-  reviewGeneratedDocs
+  reviewGeneratedDocs,
+  RPCN_SOURCE_GUIDANCE
 };

package/bin/mcp-tools/overrides-audit.js

@@ -11,7 +11,7 @@ const { findRepoRoot, getDocToolsCommand, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_
  * @param {string} args.overrides - Path to the overrides JSON file (for example "docs-data/property-overrides.json")
  * @param {string} [args.extracted] - Path to the extracted source JSON (property extractor raw output; required for the properties surface)
  * @param {string} [args.repo] - Redpanda checkout to extract raw source strings from (alternative to args.extracted, properties surface only)
- * @param {string} [args.surface] - Override surface: 'properties', 'rpk', or 'connect'
+ * @param {string} [args.surface] - Override surface: 'properties' or 'rpk'
  * @param {string} [args.output] - Also write the JSON result to this file (relative to repo root)
  * @returns {Object} Audit results with manifest and per-class summary
  */

package/bin/mcp-tools/rpcn-docs.js

@@ -12,8 +12,6 @@ const { execSync, spawnSync } = require('child_process');
 const { findRepoRoot, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
 const { getAntoraStructure } = require('./antora');
 const cache = require('./cache');
-const fs = require('fs');
-const path = require('path');
 
 /**
  * Generate Redpanda Connect connector documentation
@@ -59,19 +57,11 @@ function generateRpConnectDocs(args = {}) {
       cmdArgs.push(args.csv);
     }
 
-    // Default to using overrides.json from docs-data if it exists
-    let overridesPath = args.overrides;
-    if (!overridesPath) {
-      // Try to find docs-data/overrides.json in current directory
-      const defaultOverrides = path.join(process.cwd(), 'docs-data', 'overrides.json');
-      if (fs.existsSync(defaultOverrides)) {
-        overridesPath = defaultOverrides;
-      }
-    }
-
-    if (overridesPath) {
+    // Overrides are opt-in. Connector descriptions come from the connect and
+    // benthos specs, so no file is picked up implicitly.
+    if (args.overrides) {
       cmdArgs.push('--overrides');
-      cmdArgs.push(overridesPath);
+      cmdArgs.push(args.overrides);
     }
     if (args.cloud_version) {
       cmdArgs.push('--cloud-version');

package/cli-utils/format-helm-spec.js

@@ -9,9 +9,10 @@
  */
 function formatHelmSpec (doc) {
   const formatted = doc
-    // pandoc escapes footnote-style references inconsistently
-    .replace(/(\[\d+\])\]\./g, '$1\\].')
-    .replace(/(\[\d+\])\]\]/g, '$1\\]\\]')
+    // an array index inside a heading's link text (ingress.hosts[0].host)
+    // closes the link text early unless its "]" is escaped
+    .replace(/(\[\d+)\]\./g, '$1\\].')
+    .replace(/(\[\d+)\]\]/g, '$1\\]]')
     // a section title that is a bare URL has to be a link macro to render
     .replace(/^=== +(https?:\/\/[^[]*)\[([^\]]*)\]/gm, '=== link:++$1++[$2]')
     .replace(/^== # (.*)$/gm, '= $1')

package/cli-utils/helm-commented-values.js

@@ -24,6 +24,19 @@
  *
  *    yields `external.domain`.
  *
+ *    The description attaches to the first commented-out key after it. When
+ *    more commented-out siblings follow in the same comment run, each one
+ *    with its own plain comment above it is documented by that comment:
+ *
+ *      external:
+ *        # -- Optional domain advertised to external clients.
+ *        # domain: local
+ *        # Optional list of advertised addresses.
+ *        # addresses:
+ *
+ *    yields `external.domain` and `external.addresses`. A sibling with no
+ *    comment of its own is not documented.
+ *
  * 2. Explicit, fully-qualified syntax that works anywhere in the file:
  *
  *      # @doc external.addresses -- Optional list of advertised addresses.
@@ -89,10 +102,26 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
   const records = []
   const stack = [] // enclosing real keys: { name, indent }
 
-  // Accumulating comment block: { descLines, default, candidate }. The
-  // candidate is the key the block documents; emission is deferred to the
-  // end of the block so that a later key line at the same depth supersedes a
-  // prose line that merely looks like a key (`# example:`, `# default: 30s`).
+  // Accumulating comment block: { marked, descLines, default, candidate }.
+  // A marked block opens at a `# --` line. Its description is every comment
+  // line up to the first commented-out key, and that key (the candidate) is
+  // the one it documents, the same way helm-docs reads a `# --` block as the
+  // description of the key directly below it.
+  //
+  // Optional values often ship as a run of commented-out siblings under one
+  // marker, each with its own plain comment above it:
+  //
+  //     # -- Optional domain.
+  //     # domain: local
+  //     # Optional list of addresses.
+  //     # addresses:
+  //
+  // Once a block has its key, a plain comment line at that key's depth (or
+  // shallower) ends it and opens an unmarked block for the next sibling, so
+  // `addresses` is documented by its own comment instead of handing its key
+  // line to the domain description. An unmarked block is only ever emitted
+  // when it has description text and a key; it never becomes a dead marker.
+  // The run ends at the first non-comment line, as a marked block does.
   let block = null
   let atDoc = null // accumulating @doc entry: { path, descLines, default }
   let skipScalarIndent = -1 // inside a block scalar when >= 0
@@ -135,6 +164,7 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
   // The generator drops these; the linter reports them, because their
   // description silently never ships.
   const emitDead = (b) => {
+    if (!b.marked) return
     record({
       kind: 'dead-marker',
       descLines: b.descLines,
@@ -145,12 +175,26 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
     })
   }
 
+  const openUnmarkedBlock = (line, firstDescLine) => ({
+    marked: false,
+    markerLine: line,
+    lastLine: line,
+    descLines: firstDescLine === null ? [] : [firstDescLine],
+    default: '',
+    annotations: {},
+    candidate: null,
+  })
+
   // Emit the active block's candidate, if any, and close the block. The
   // emitted key suppresses its own commented subtree until real content
   // appears, so nested example structures do not emit bogus paths.
   const flushBlock = () => {
     if (!block) return
-    if (block.candidate) {
+    if (block.candidate && !block.marked && !block.descLines.some((l) => l.trim() !== '')) {
+      // An unmarked sibling with no comment of its own has nothing to say;
+      // still suppress its commented subtree.
+      suppressInnerIndent = block.candidate.effIndent
+    } else if (block.candidate) {
       const { name, effIndent } = block.candidate
       const parents = stack.filter((k) => k.indent < effIndent).map((k) => k.name)
       record({
@@ -233,13 +277,26 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
       // "key" is a URL scheme and the "value" is the scheme-relative part.
       const simpleValue = (value === '' || !/\s/.test(value)) && !value.startsWith('/')
       if (block && simpleValue) {
-        if (!block.candidate || effIndent <= block.candidate.effIndent) {
-          // The last key-shaped line at the block's shallowest depth wins:
-          // an earlier line at the same depth was prose shaped like a key,
-          // and deeper lines are nested example structures.
-          block.candidate = { name: commentedKey[3], effIndent }
+        const key = { name: commentedKey[3], effIndent }
+        if (!block.candidate || effIndent < block.candidate.effIndent) {
+          // The first key line after the description is the documented key.
+          // A shallower key replaces it, because the deeper line was a nested
+          // example structure rather than the key itself.
+          block.candidate = key
+          block.lastLine = i
+        } else if (effIndent > block.candidate.effIndent) {
+          // A nested line of the documented key's commented-out example.
+          block.lastLine = i
+        } else {
+          // A sibling key with no comment of its own. The documented key is
+          // complete; the sibling opens an unmarked block, which flushBlock
+          // drops because it has no description, while still suppressing
+          // the sibling's own commented subtree.
+          flushBlock()
+          suppressInnerIndent = -1
+          block = openUnmarkedBlock(i, null)
+          block.candidate = key
         }
-        block.lastLine = i
         continue
       }
     }
@@ -248,18 +305,30 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
     if (descMarker) {
       flushAtDoc()
       flushBlock()
-      block = { markerLine: i, lastLine: i, descLines: [descMarker[1]], default: '', annotations: {}, candidate: null }
+      block = { marked: true, markerLine: i, lastLine: i, descLines: [descMarker[1]], default: '', annotations: {}, candidate: null }
       continue
     }
 
     const comment = line.match(COMMENT_RE)
     if (comment && line.trim().startsWith('#')) {
       if (atDoc) { atDoc.descLines.push(comment[1]); atDoc.lastLine = i }
-      // Description lines precede the documented key; once a candidate
-      // exists, trailing comment lines belong to its example structure and
-      // only extend the span.
+      // Description lines precede the documented key.
       else if (block && !block.candidate) { block.descLines.push(comment[1]); block.lastLine = i }
-      else if (block) block.lastLine = i
+      else if (block) {
+        // After the key: deeper lines, list items, and bare `#` lines belong
+        // to its commented-out example. Prose at the key's own depth or
+        // shallower is the description of the next commented-out sibling.
+        const [, before, after] = line.match(/^(\s*)#(\s*)/)
+        const proseIndent = before.length + Math.max(0, after.length - 1)
+        const text = comment[1].trim()
+        if (text === '' || text.startsWith('- ') || text === '-' || proseIndent > block.candidate.effIndent) {
+          block.lastLine = i
+        } else {
+          flushBlock()
+          suppressInnerIndent = -1
+          block = openUnmarkedBlock(i, comment[1])
+        }
+      }
       continue
     }
 
@@ -270,8 +339,9 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
     flushAtDoc()
 
     const realKey = line.match(REAL_KEY_RE)
-    if (attachRealKeys && realKey && block && !block.candidate && block.lastLine === i - 1) {
-      // helm-docs' own attachment: the block sits DIRECTLY above a real key.
+    if (attachRealKeys && realKey && block && block.marked && !block.candidate && block.lastLine === i - 1) {
+      // helm-docs' own attachment: the marked block sits DIRECTLY above a
+      // real key.
       const indent = realKey[1].length
       while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop()
       const name = realKey[2].replace(/^"|"$/g, '')

package/cli-utils/self-managed-docs-branch.js

@@ -43,51 +43,57 @@ async function fetchRemoteAntoraVersion(deps = {}) {
 }
 
 /**
- * Determines the appropriate documentation branch for a given operator tag based on the remote Antora version.
+ * Reports whether a branch exists in the docs repository.
  *
- * Normalizes the input tag, extracts the major.minor version, and applies version-specific logic to select the correct branch. Verifies that the chosen branch exists in the remote repository.
+ * @param {string} branch - Branch name, such as "main" or "v/25.1".
+ * @returns {boolean} True when `git ls-remote` finds the branch.
+ */
+function docsBranchExists(branch) {
+  const repo = 'https://github.com/redpanda-data/docs.git'
+  return spawnSync('git', ['ls-remote', '--exit-code', '--heads', repo, `refs/heads/${branch}`], {
+    stdio: 'ignore'
+  }).status === 0
+}
+
+/**
+ * Determines the appropriate documentation branch for a given operator tag or branch based on the remote Antora version.
+ *
+ * Normalizes the input, extracts the major.minor version, and applies version-specific logic to select the correct branch. Verifies that the chosen branch exists in the remote repository.
+ * A ref with no version, such as `main`, `dev`, or a feature branch, holds content for the next release, which the docs repository keeps on `main`.
  *
- * @param {string} operatorTag - The operator tag to evaluate (for example, "operator/v25.1.2" or "v25.1.2").
+ * @param {string} operatorRef - The operator tag or branch to evaluate (for example, "operator/v25.1.2", "v25.1.2", "release/v25.1.x", or "main").
+ * @param {object} [deps] - Injectable for tests: { antoraVersion, branchExists, fetchImpl, token }.
  * @returns {Promise<string>} The name of the documentation branch to use.
  *
- * @throws {Error} If the tag cannot be parsed or if the determined branch does not exist in the remote repository.
+ * @throws {Error} If the Antora version cannot be fetched or if the determined branch does not exist in the remote repository.
  */
-async function determineDocsBranch(operatorTag) {
-  // Strip any "operator/" prefix
-  const TAG = operatorTag.replace(/^(?:operator|release)\//, '')
-  // Pull in the remote Antora version
-  const ANTORA = await fetchRemoteAntoraVersion()
+async function determineDocsBranch(operatorRef, deps = {}) {
+  const branchExists = deps.branchExists || docsBranchExists
+  // Strip any "operator/" or "release/" prefix
+  const TAG = operatorRef.replace(/^(?:operator|release)\//, '')
   // Extract v<major>.<minor>
   const mm = TAG.match(/^v(\d+\.\d+)/)
   const filtered = mm ? `v${mm[1]}` : null
 
-  if (!filtered) {
-    throw new Error(`Could not parse major.minor from ${TAG}`)
-  }
-  // We started versioning the operator in line with Redpanda core versions. But when v2.4.x was the latest version, the docs were still on 25.1 and v25.1.x of the operator was still in beta. So we need to handle this special case.
   let branch
-  if (filtered === 'v2.4') {
-    if (ANTORA === '25.1') {
+  if (!filtered) {
+    branch = 'main'
+  } else {
+    // Pull in the remote Antora version
+    const ANTORA = deps.antoraVersion || await fetchRemoteAntoraVersion(deps)
+    // We started versioning the operator in line with Redpanda core versions. But when v2.4.x was the latest version, the docs were still on 25.1 and v25.1.x of the operator was still in beta. So we need to handle this special case.
+    if (filtered === 'v2.4') {
+      branch = ANTORA === '25.1' ? 'main' : 'v/24.3'
+    // For all other versions use the v<major>.<minor> branch unless it is the current version, in which case we use 'main'.
+    } else if (filtered === `v${ANTORA}`) {
       branch = 'main'
     } else {
-      branch = 'v/24.3'
+      branch = `v/${filtered.slice(1)}`
     }
-  // For all other versions use the v<major>.<minor> branch unless it is the current version, in which case we use 'main'.
-  } else if (filtered === `v${ANTORA}`) {
-    branch = 'main'
-  } else {
-    branch = `v/${filtered.slice(1)}`
   }
 
-  // Verify branch exists
-  const repo = 'https://github.com/redpanda-data/docs.git'
-  const ref  = `refs/heads/${branch}`
-  const ok = spawnSync('git', ['ls-remote', '--exit-code', '--heads', repo, ref], {
-    stdio: 'ignore'
-  }).status === 0
-
-  if (!ok) {
-    throw new Error(`Docs branch ${branch} not found in ${repo}`)
+  if (!branchExists(branch)) {
+    throw new Error(`Docs branch ${branch} not found in https://github.com/redpanda-data/docs.git`)
   }
 
   return branch

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

@@ -412,7 +412,8 @@ 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 and `modules/components/examples/**` as examples 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.
+. 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.
 
@@ -490,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:
 
@@ -511,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.
@@ -878,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
@@ -1113,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 })