@redpanda-data/docs-extensions-and-macros 5.3.2 → 5.3.4

package/extensions/generate-rp-connect-info.js

@@ -428,13 +428,19 @@ module.exports.register = function ({ config }) {
   function buildContextSwitcher (connectorRows, currentRow, variant) {
     const capitalize = (value) => value.charAt(0).toUpperCase() + value.slice(1)
     const orderedRows = [currentRow, ...connectorRows.filter((row) => row !== currentRow)]
-    const data = {}
+    // The process-context-switcher extension and the UI's context-switcher partial
+    // both expect an array of { name, to } items; `to` is a root-relative pub URL.
+    const items = []
     for (const row of orderedRows) {
       const link = (variant === 'cloud' && row.redpandaCloudUrl) || row.redpandaConnectUrl
       if (!link) continue
       const type = row.type.trim()
-      data[type.toLowerCase()] = { name: capitalize(type), to: link }
+      // First occurrence wins: orderedRows puts the current page's row first,
+      // so a connector with duplicate types keeps its own entry. (The old
+      // object-keyed build let later rows overwrite earlier ones.)
+      if (items.some((item) => item.name === capitalize(type))) continue
+      items.push({ name: capitalize(type), to: link })
     }
-    return JSON.stringify(data)
+    return JSON.stringify(items)
   }
 }

package/extensions/process-context-switcher.js

@@ -74,6 +74,11 @@ module.exports.register = function ({ config }) {
           item.to = currentResourceId;
           hasChanges = true;
           logger.debug(`Replaced 'current' with '${currentResourceId}' in context-switcher`);
+        } else if (typeof item.to === 'string' && item.to.startsWith('/')) {
+          // Root-relative URLs (e.g. pub.url values set by generate-rp-connect-info)
+          // need no resolution or target injection: the UI's resolve-resource helper
+          // passes them through, and the producer decorates every variant directly.
+          continue;
         } else if (item.to !== currentResourceId) {
           // For non-current items, find and update the target page
           const targetPage = findPageByResourceId(item.to, contentCatalog, page);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.3.2",
+  "version": "5.3.4",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/redpanda-connect/rpcn-connector-docs-handler.js

@@ -501,6 +501,52 @@ function updateWhatsNew ({ dataDir, oldVersion, newVersion, binaryAnalysis }) {
   }
 }
 
+/**
+ * Derive the fragment anchor for a connector field heading.
+ *
+ * Field docs render each field as a section heading (for example,
+ * `=== \`batching.byte_size\``), and the docs site builds section IDs with
+ * `idprefix: ''` and `idseparator: '-'` (set in the shared global-attributes
+ * component loaded by the Antora playbook). Under those settings Asciidoctor
+ * derives IDs by downcasing the heading text, dropping characters that are
+ * not word characters, hyphens, dots, or spaces (so `[]` array markers are
+ * discarded), converting runs of dots and spaces to a single `-`, and
+ * trimming any leading or trailing separator.
+ *
+ * Examples of rendered IDs this must match:
+ * - `checkpoint_limit`                    -> `checkpoint_limit`
+ * - `batching.byte_size`                  -> `batching-byte_size`
+ * - `batching.processors[]`               -> `batching-processors`
+ * - `sasl[].aws.credentials.from_ec2_role` -> `sasl-aws-credentials-from_ec2_role`
+ *
+ * Collision caveat: Asciidoctor de-duplicates repeated IDs on a page by
+ * appending `-2`, `-3`, ... to later occurrences. If two fields on one page
+ * normalize to the same anchor, the generated link resolves to the first
+ * heading and the second gets the suffixed ID. This helper cannot detect
+ * that, so a wrong-but-plausible link on a page with near-duplicate field
+ * names should be checked against this behavior first.
+ *
+ * @param {string} fieldName - Field name as it appears in the connector data
+ * @returns {string} Fragment anchor matching the rendered heading ID
+ */
+function fieldAnchor (fieldName) {
+  const anchor = String(fieldName)
+    .toLowerCase()
+    // Characters that are invalid in section IDs (for example, `[` and `]`
+    // array markers) are removed outright, matching Asciidoctor's
+    // InvalidSectionIdCharsRx. The dots still supply the separators, so
+    // every `[]` case stays correct (`sasl[].aws` -> `sasl-aws`).
+    .replace(/[^ \w\-.]+/g, '')
+    // idseparator '-' replaces runs of spaces and dots with a single hyphen.
+    .replace(/[ .]+/g, '-')
+    // idprefix '' means no leading separator, and Asciidoctor chomps a
+    // trailing separator.
+    .replace(/^-+/, '')
+    .replace(/-+$/, '')
+  // A name that normalizes to nothing would emit a malformed `#[...]` xref.
+  return anchor || String(fieldName)
+}
+
 /**
  * Build a fields table for whats-new.adoc
  * @param {Array} fields - Field data
@@ -541,7 +587,7 @@ function buildFieldsTable (fields, capFn) {
 
       componentList += `*${typeLabel}:*\n\n`
       names.forEach(name => {
-        componentList += `* xref:components:${type}/${name}.adoc#${fieldName}[${name}]\n`
+        componentList += `* xref:components:${type}/${name}.adoc#${fieldAnchor(fieldName)}[${name}]\n`
       })
     }
 
@@ -611,7 +657,7 @@ function buildChangedDefaultsTable (changedDefaults, capFn) {
 
       componentList += `*${typeLabel}:*\n\n`
       names.forEach(name => {
-        componentList += `* xref:components:${type}/${name}.adoc#${info.field}[${name}]\n`
+        componentList += `* xref:components:${type}/${name}.adoc#${fieldAnchor(info.field)}[${name}]\n`
       })
     }
 
@@ -2014,5 +2060,8 @@ module.exports = {
   updateWhatsNew,
   capToTwoSentences,
   augmentConnectorData,
-  buildCleanOssData
+  buildCleanOssData,
+  fieldAnchor,
+  buildFieldsTable,
+  buildChangedDefaultsTable
 }

package/tools/rpk-docs/generate-rpk-docs.js

@@ -15,6 +15,19 @@ Object.entries(helpers).forEach(([name, fn]) => {
 // Template paths
 const TEMPLATES_DIR = path.resolve(__dirname, './templates')
 
+// Full command paths from the tree being generated (e.g. "rpk ai run codex").
+// Registered by generateRpkDocs so formatDescription can wrap real multi-word
+// command paths as a unit instead of heuristically wrapping `rpk` alone.
+let knownCommandPaths = new Set()
+
+/**
+ * Register the set of real command paths for the current generation run.
+ * @param {string[]} paths - Full command paths (e.g. "rpk ai run codex")
+ */
+function registerKnownCommandPaths(paths) {
+  knownCommandPaths = new Set(paths)
+}
+
 /**
  * Register a Handlebars partial from file
  * @param {string} name - Partial name
@@ -1607,6 +1620,25 @@ function formatDescription(desc, customTransformations = null, options = {}) {
     // Fix product name: "Redpanda cloud" → "Redpanda Cloud" (product name)
     .replace(/Redpanda\s+cloud\b/g, 'Redpanda Cloud')
 
+  // === RPK COMMAND FORMATTING (known paths first, ground truth) ===
+  // Wrap full multi-word command paths that exist in the generated tree
+  // (e.g. "rpk ai run codex" -> `rpk ai run codex`). The heuristic formatter
+  // below only ever matches "rpk <word>", so without this pass it wraps
+  // `rpk` alone and splits the command in half. Matching against the real
+  // tree means prose that merely resembles a command is never wrapped.
+  if (knownCommandPaths.size > 0) {
+    result = result.replace(/(?<![`\w])rpk((?: [a-z][-a-z0-9]*)+)/g, (match, rest) => {
+      const tokens = rest.trim().split(' ')
+      for (let n = tokens.length; n >= 2; n--) {
+        const path = `rpk ${tokens.slice(0, n).join(' ')}`
+        if (knownCommandPaths.has(path)) {
+          return `\`${path}\`` + match.slice(path.length)
+        }
+      }
+      return match
+    })
+  }
+
   // === RPK COMMAND FORMATTING (context-aware) ===
   // Process "rpk X" patterns based on what follows
   result = result.replace(/(?<![`\w])rpk(\s+)([a-z][-a-z0-9]*)(?:\s+|(?=[.,;:!?)'"}\]]|$))/gi, (match, space, word, offset, str) => {
@@ -1702,6 +1734,11 @@ function formatDescription(desc, customTransformations = null, options = {}) {
   // Add backticks around standalone file names (not inside paths)
   result = result.replace(/(?<![`/])(redpanda\.yaml|rpk\.yaml)(?!`)/gi, '`$1`')
 
+  // Add backticks around internal topic names (_redpanda.transform_logs,
+  // _redpanda.audit_log, ...). The leading underscore is also an AsciiDoc
+  // italics delimiter, so these must never render as bare prose.
+  result = result.replace(/(?<![`\w/])(_redpanda(?:\.[a-z_]+)+)(?!`)/g, '`$1`')
+
   // Add backticks around standalone "rpk" (at end of phrase, before punctuation)
   // Also exclude rpk inside paths (preceded by /)
   result = result.replace(/(?<![`\w/])rpk(?=[\s]*[.,;:!?)'"}\]]|[\s]*$)/g, '`rpk`')
@@ -1730,9 +1767,13 @@ function formatDescription(desc, customTransformations = null, options = {}) {
     result = result.replace(`__EARLY_CODE_BLOCK_${i}__`, () => transformed)
   })
 
-  // Restore inline code
+  // Restore inline code. Spans are verbatim, but rules flagged applyToCode
+  // (like the rpai -> rpk ai binary-name rewrite) must reach them the same
+  // way they reach code blocks, or the internal binary name survives in
+  // published spans like `rpai auth token`.
   inlineCode.forEach((code, i) => {
-    result = result.replace(`__INLINE_CODE_${i}__`, () => code)
+    const transformed = applyTextTransformations(code, customTransformations, { code: true })
+    result = result.replace(`__INLINE_CODE_${i}__`, () => transformed)
   })
 
   // Restore xrefs
@@ -2173,6 +2214,12 @@ function capToTwoSentences(desc) {
   // The pattern matches: colon, optional whitespace/newlines, then indented content
   cleaned = cleaned.replace(/:\s*\n+[ \t]+.+$/s, ':')
 
+  // A paragraph break is a sentence boundary even when the paragraph has no
+  // terminal punctuation (cobra short descriptions often lack one: "Generate
+  // a trial license\n\nThis command..."). Without this, flattening newlines
+  // glues the paragraphs into one run-on "sentence".
+  cleaned = cleaned.replace(/([^.!?:\s])[ \t]*\n[ \t]*\n/g, '$1.\n\n')
+
   // Normalize newlines to spaces for inline use (like :description: attribute)
   const singleLine = cleaned.replace(/\s*\n+\s*/g, ' ').trim()
 
@@ -2202,6 +2249,14 @@ function capToTwoSentences(desc) {
   // dropped by the sentence matcher
   normalized = normalized.replace(/(\d)\.(\d)/g, '$1__DECIMAL__$2')
 
+  // Protect ALL mid-token periods (no whitespace after): dotted names like
+  // _redpanda.transform_logs or URLs like redpanda.com/contact are not
+  // sentence boundaries. Without this the sentence matcher below cannot
+  // match the sentence containing the token, silently drops everything up
+  // to the mid-token period, and emits the tail fragment as a "sentence"
+  // ("View logs for a transform. transform_logs.").
+  normalized = normalized.replace(/\.(?=\S)/g, '__MIDDOT__')
+
   // Match sentences
   let sentences = normalized.match(/[^.!?]+[.!?]+(?:\s|$)/g)
 
@@ -2217,6 +2272,7 @@ function capToTwoSentences(desc) {
   if (!sentences || sentences.length === 0) {
     // Restore and return
     let result = normalized.replace(/__DECIMAL__/g, '.')
+    result = result.replace(/__MIDDOT__/g, '.')
     placeholders.forEach(({ ph, original }) => {
       result = result.replace(ph, original)
     })
@@ -2230,6 +2286,7 @@ function capToTwoSentences(desc) {
 
   // Restore decimal points
   result = result.replace(/__DECIMAL__/g, '.')
+  result = result.replace(/__MIDDOT__/g, '.')
 
   // Restore abbreviations
   placeholders.forEach(({ ph, original }) => {
@@ -2578,6 +2635,9 @@ async function generateRpkDocs(options = {}) {
   // Flatten command tree
   const commands = flattenCommands(tree)
 
+  // Let formatDescription wrap real multi-word command paths as a unit
+  registerKnownCommandPaths(commands.map(c => c.path))
+
   // Determine which managed plugins are protected this run: explicitly
   // passed by the caller (failed installs) merged with auto-detection of
   // absent or shim-only plugin subtrees. Protection covers the whole
@@ -3000,6 +3060,21 @@ async function generateRpkDocs(options = {}) {
     }
 
     try {
+      // A page that HAD a Flags section and loses it in this render is the
+      // signature of missing flag data (a snapshot without extraction, or a
+      // curated table removed before the extracted one exists). Nothing else
+      // catches this class: the run exits 0 with a clean log while the
+      // published page silently drops its flag documentation (seen on
+      // rpk connect run).
+      if (fs.existsSync(filePath)) {
+        const previous = fs.readFileSync(filePath, 'utf8')
+        if (/^== Flags$/m.test(previous) && !/^== Flags$/m.test(content)) {
+          console.warn(
+            `⚠️  ${commandPath}: the previously rendered page had a Flags section and this render has none. ` +
+            'The command likely lost its flag data (snapshot without extraction, or a curated Flags override removed too early).'
+          )
+        }
+      }
       fs.writeFileSync(filePath, content, 'utf8')
       writtenFiles.add(filePath)
       filesGenerated++
@@ -3121,5 +3196,6 @@ module.exports = {
   // Exported for testing
   filterExamples,
   formatExamples,
-  applyTextTransformationsToExamples
+  applyTextTransformationsToExamples,
+  registerKnownCommandPaths
 }

package/tools/rpk-docs/rpk-docs-handler.js

@@ -894,7 +894,7 @@ function loadVersionedJson(version, dataDir) {
  *   version (the page note renders "introduced in <plugin> version X"), not
  *   the rpk version, because plugins release on their own cadence.
  */
-function updateOverridesWithIntroducedVersions(diffData, overridesPath, version, pluginVersions = {}) {
+function updateOverridesWithIntroducedVersions(diffData, overridesPath, version, pluginVersions = {}, options = {}) {
   const hasNewCommands = diffData.details.newCommands && diffData.details.newCommands.length > 0
   const hasNewFlags = diffData.details.newFlags && diffData.details.newFlags.length > 0
 
@@ -908,6 +908,23 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version,
     return pluginVersions[topLevel] || version
   }
 
+  // Plugin-owned entries are only stamped when the caller vouches that the
+  // baseline is manifest-adjacent to this run's plugin version (see
+  // isPluginStampAttributable). "New relative to the snapshot" is not "new
+  // in this release" when the snapshot skipped releases. Callers that omit
+  // attributablePlugins keep legacy stamp-everything behavior.
+  const attributable = options.attributablePlugins
+    ? new Set(options.attributablePlugins)
+    : null
+  const skippedByPlugin = new Map()
+  const stampable = (cmdPath) => {
+    const topLevel = cmdPath.split(' ')[1]
+    if (!KNOWN_PLUGINS.includes(topLevel) || !attributable) return true
+    if (attributable.has(topLevel)) return true
+    skippedByPlugin.set(topLevel, (skippedByPlugin.get(topLevel) || 0) + 1)
+    return false
+  }
+
   let overrides = {}
   if (fs.existsSync(overridesPath)) {
     try {
@@ -929,6 +946,7 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version,
   if (hasNewCommands) {
     for (const newCmd of diffData.details.newCommands) {
       const cmdPath = newCmd.path
+      if (!stampable(cmdPath)) continue
       if (!overrides.commands[cmdPath]) {
         overrides.commands[cmdPath] = {}
       }
@@ -945,6 +963,7 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version,
     for (const newFlag of diffData.details.newFlags) {
       const cmdPath = newFlag.commandPath
       const flagName = newFlag.flagName
+      if (!stampable(cmdPath)) continue
 
       if (!overrides.commands[cmdPath]) {
         overrides.commands[cmdPath] = {}
@@ -964,6 +983,15 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version,
     }
   }
 
+  for (const [plugin, count] of skippedByPlugin) {
+    console.warn(
+      `\u26a0 Skipped stamping introducedInVersion for ${count} new '${plugin}' entr${count === 1 ? 'y' : 'ies'}: ` +
+      `the baseline snapshot's ${plugin} version is not the release immediately before ` +
+      `${pluginVersions[plugin] || version} in the plugin manifest, so the introduction ` +
+      'version cannot be attributed automatically. Attribute manually against released binaries.'
+    )
+  }
+
   if (commandsUpdated > 0 || flagsUpdated > 0) {
     fs.writeFileSync(overridesPath, JSON.stringify(overrides, null, 2), 'utf8')
     const updates = []
@@ -1444,6 +1472,75 @@ function fetchLatestPluginVersion(plugin) {
   }
 }
 
+/**
+ * Fetch the ordered list of published versions for a plugin from its
+ * manifest. Cached per plugin for the process lifetime.
+ * @param {string} plugin - rpk command name (ai, connect, k8s, check)
+ * @returns {string[]|null} Versions in manifest (release) order, or null
+ */
+const pluginManifestVersionsCache = new Map()
+function fetchPluginManifestVersions(plugin) {
+  if (pluginManifestVersionsCache.has(plugin)) {
+    return pluginManifestVersionsCache.get(plugin)
+  }
+  const slug = PLUGIN_MANIFEST_SLUGS[plugin] || plugin
+  const result = spawnSync('curl', [
+    '-fsSL', '--retry', '3', '--connect-timeout', '15', '--max-time', '30',
+    `${PLUGIN_MANIFEST_HOST}/${slug}/manifest.json`
+  ], { encoding: 'utf8', timeout: 60000 })
+  let versions = null
+  if (result.status === 0) {
+    try {
+      versions = (JSON.parse(result.stdout).archives || []).map(a => a.version)
+    } catch (err) {
+      console.warn(`Could not parse plugin manifest for ${plugin}: ${err.message}`)
+    }
+  } else {
+    console.warn(`Could not fetch plugin manifest for ${plugin} (slug: ${slug})`)
+  }
+  pluginManifestVersionsCache.set(plugin, versions)
+  return versions
+}
+
+/**
+ * Decide whether new commands under a plugin can truthfully be attributed
+ * to newVersion: only when the baseline snapshot recorded the plugin
+ * version AND that version is the release immediately before newVersion in
+ * the plugin's manifest. Any gap means a "new" command may have shipped in
+ * an intermediate release, so a stamp would fabricate history (30 rpk ai
+ * commands were once labeled 0.2.32 when they shipped in 0.2.26/0.2.28).
+ * @param {string} plugin - rpk command name
+ * @param {string|undefined} oldVersion - Plugin version recorded in the
+ *   baseline snapshot's plugin_versions, if any
+ * @param {string} newVersion - Plugin version in this run
+ * @returns {boolean}
+ */
+function isPluginStampAttributable(plugin, oldVersion, newVersion) {
+  if (!oldVersion || !newVersion) return false
+  if (oldVersion === newVersion) return true
+  const versions = fetchPluginManifestVersions(plugin)
+  if (!versions) return false
+  const oldIdx = versions.indexOf(oldVersion)
+  const newIdx = versions.indexOf(newVersion)
+  return oldIdx !== -1 && newIdx === oldIdx + 1
+}
+
+/**
+ * Compute the set of plugins whose new commands may be stamped this run.
+ * @param {Object} oldPluginVersions - plugin_versions from the baseline snapshot
+ * @param {Object} newPluginVersions - plugin_versions for this run
+ * @returns {Set<string>}
+ */
+function attributablePluginSet(oldPluginVersions = {}, newPluginVersions = {}) {
+  const attributable = new Set()
+  for (const plugin of Object.keys(newPluginVersions)) {
+    if (isPluginStampAttributable(plugin, oldPluginVersions[plugin], newPluginVersions[plugin])) {
+      attributable.add(plugin)
+    }
+  }
+  return attributable
+}
+
 /**
  * Check whether a plugin node contains real plugin commands, as opposed to
  * only the install/uninstall/upgrade shim compiled into rpk itself.
@@ -1952,7 +2049,12 @@ async function handleRpkDocsGeneration(options = {}) {
             pluginDiffData,
             overridesPath || path.join(dataDir, 'rpk-overrides.json'),
             resolvedVersion,
-            { [plugin]: resolvedVersion }
+            { [plugin]: resolvedVersion },
+            {
+              attributablePlugins: isPluginStampAttributable(
+                plugin, (jsonData.plugin_versions || {})[plugin], resolvedVersion
+              ) ? [plugin] : []
+            }
           )
         }
 
@@ -1996,7 +2098,9 @@ async function handleRpkDocsGeneration(options = {}) {
             newDeprecatedCommands: jsonData.deprecated_commands || {}
           })
           if (stampDiff.details.newCommands.length > 0 || stampDiff.details.newFlags.length > 0) {
-            updateOverridesWithIntroducedVersions(stampDiff, effectiveOverridesPath, rpkVersion, pluginVersions)
+            updateOverridesWithIntroducedVersions(stampDiff, effectiveOverridesPath, rpkVersion, pluginVersions, {
+              attributablePlugins: attributablePluginSet(oldDataForStamp.plugin_versions, pluginVersions)
+            })
           }
         }
       }
@@ -2400,7 +2504,9 @@ async function handleRpkDocsGeneration(options = {}) {
         // cadence, so the rpk version would be wrong and the page note would
         // render "introduced in <plugin> version <rpk version>").
         if ((diffData.details.newCommands.length > 0 || diffData.details.newFlags.length > 0) && effectiveOverridesPath) {
-          updateOverridesWithIntroducedVersions(diffData, effectiveOverridesPath, rpkVersion, pluginVersions)
+          updateOverridesWithIntroducedVersions(diffData, effectiveOverridesPath, rpkVersion, pluginVersions, {
+            attributablePlugins: attributablePluginSet(oldData.plugin_versions, pluginVersions)
+          })
         }
 
         // Update what's-new file if requested
@@ -2819,6 +2925,11 @@ module.exports = {
   getPlatformDescription,
   getCurrentPlatform,
   updateOverridesWithIntroducedVersions,
+  isPluginStampAttributable,
+  attributablePluginSet,
+  fetchPluginManifestVersions,
+  // Exported for tests to seed manifest data without network access
+  pluginManifestVersionsCache,
   filterDiffForWhatsNew,
   computeDescriptionCoverage,
   updateWhatsNewFile,

package/tools/rpk-docs/templates/command.hbs

@@ -1,11 +1,10 @@
-{{!-- Cloud-only wrapper start --}}
-{{#if cloudOnly}}
-ifdef::env-cloud[]
-{{/if}}
-{{!-- Self-hosted-only wrapper start --}}
-{{#if selfHostedOnly}}
-ifndef::env-cloud[]
-{{/if}}
+{{!-- cloudOnly/selfHostedOnly deliberately do NOT wrap the page. The
+     gating that matters happens inside the single-source tag region
+     (subcommand rows, flags, content items): includes only extract that
+     region, and the docs component never builds with env-cloud set, so a
+     page-level conditional is dead code at best and an empty, untitled
+     page at worst. Availability pages are excluded from cloud by not
+     generating a stub for them in cloud-docs. --}}
 = {{commandPath}}
 :description: {{{wrapDescriptionPassthrough shortDesc}}}
 {{#if pageAliases}}
@@ -583,11 +582,3 @@ include::{{{this}}}[]
 {{> content-item this commandPath=../commandPath}}
 {{/each}}
 // end::single-source[]
-{{!-- Self-hosted-only wrapper end --}}
-{{#if selfHostedOnly}}
-endif::[]
-{{/if}}
-{{!-- Cloud-only wrapper end --}}
-{{#if cloudOnly}}
-endif::[]
-{{/if}}