@redpanda-data/docs-extensions-and-macros 5.2.0 → 5.2.2

package/bin/doc-tools.js

@@ -26,6 +26,7 @@ const {
   diffDirs,
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
+  updatePropertiesJsonWithVersion,
   cleanupOldDiffs
 } = require('../cli-utils/diff-utils')
 
@@ -1002,6 +1003,12 @@ automation
 
           if (overridesPath && fs.existsSync(overridesPath)) {
             updatePropertyOverridesWithVersion(overridesPath, diffData, newTag)
+            // The overrides were baked into the extracted JSON during Phase 1,
+            // before the stamp above existed. Stamp the JSON too, so the
+            // AsciiDoc generated in Phase 3 shows "Introduced in" for
+            // properties new in this release instead of one release late.
+            const extractedJsonPath = path.resolve(outputDir, 'attachments', `redpanda-properties-${newTag}.json`)
+            updatePropertiesJsonWithVersion(extractedJsonPath, diffData, newTag)
           }
         }
       } catch (err) {

package/cli-utils/diff-utils.js

@@ -193,6 +193,88 @@ function updatePropertyOverridesWithVersion (overridesPath, diffData, newTag) {
   }
 }
 
+/**
+ * Stamp version information for new properties directly into an extracted
+ * properties JSON file (redpanda-properties-<tag>.json).
+ *
+ * Overrides are baked into this JSON during extraction, which happens before
+ * updatePropertyOverridesWithVersion stamps new properties into the overrides
+ * file — so without this step the AsciiDoc rendered from the JSON misses the
+ * "Introduced in" line for properties added in the release being generated
+ * (it would only appear on the next release's run).
+ *
+ * @param {string} jsonPath - Path to the extracted properties JSON file
+ * @param {object} diffData - Diff data from property comparison
+ * @param {string} newTag - Version tag for new properties (e.g., "v26.1.13")
+ */
+function updatePropertiesJsonWithVersion (jsonPath, diffData, newTag) {
+  try {
+    const newProperties = diffData.details?.newProperties || []
+    if (newProperties.length === 0) return
+    if (!fs.existsSync(jsonPath)) {
+      console.warn(`Warning: Cannot stamp versions: ${jsonPath} does not exist`)
+      return
+    }
+
+    // The stamp is a textual insertion, NOT a parse/re-serialize round-trip:
+    // JSON.stringify would corrupt values JavaScript numbers cannot represent
+    // (uint64 maxima like 18446744073709551615) and reformat floats (0.0 → 0)
+    // throughout the Python-generated file.
+    let raw = fs.readFileSync(jsonPath, 'utf8')
+    const indentUnit = (raw.match(/^([ \t]+)"/m) || [null, '    '])[1]
+
+    let stampedCount = 0
+    newProperties.forEach(prop => {
+      const updated = insertVersionIntoRawJson(raw, prop.name, newTag, indentUnit)
+      if (updated) {
+        raw = updated
+        stampedCount++
+      }
+    })
+
+    if (stampedCount > 0) {
+      JSON.parse(raw) // validate the surgical edits before touching the file
+      fs.writeFileSync(jsonPath, raw, 'utf8')
+      console.log(`Done: Stamped "Introduced in ${newTag}" on ${stampedCount} new ${stampedCount === 1 ? 'property' : 'properties'} in ${path.basename(jsonPath)}`)
+    }
+  } catch (error) {
+    console.error(`Warning: Failed to stamp versions into properties JSON: ${error.message}`)
+  }
+}
+
+/**
+ * Insert a `"version": "<newTag>",` field at the top of one property's object
+ * in the raw JSON text, leaving every other byte untouched.
+ *
+ * @param {string} raw - Full JSON file content
+ * @param {string} propName - Property key to stamp
+ * @param {string} newTag - Version tag to insert
+ * @param {string} indentUnit - One level of the file's indentation
+ * @returns {string|null} Updated content, or null when the property was not
+ *   found or already carries a version field.
+ */
+function insertVersionIntoRawJson (raw, propName, newTag, indentUnit) {
+  // Anchor the search to the top-level "properties" section when present, so
+  // an identically named key elsewhere (e.g. under "definitions") is not hit.
+  const sectionMatch = raw.match(new RegExp(`^${indentUnit}"properties": \\{`, 'm'))
+  const searchFrom = sectionMatch ? raw.indexOf(sectionMatch[0]) : 0
+
+  const escapedName = propName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const keyMatch = new RegExp(`^([ \t]+)"${escapedName}": \\{[ \t]*$`, 'm').exec(raw.slice(searchFrom))
+  if (!keyMatch) return null
+
+  const keyIndent = keyMatch[1]
+  const objStart = searchFrom + keyMatch.index + keyMatch[0].length
+
+  // Skip when the object already has a version field (scan up to its closing brace).
+  const close = new RegExp(`^${keyIndent}\\}`, 'm').exec(raw.slice(objStart))
+  const objBody = raw.slice(objStart, close ? objStart + close.index : raw.length)
+  if (new RegExp(`^${keyIndent}${indentUnit}"version":`, 'm').test(objBody)) return null
+
+  const insertion = `\n${keyIndent}${indentUnit}"version": ${JSON.stringify(newTag)},`
+  return raw.slice(0, objStart) + insertion + raw.slice(objStart)
+}
+
 /**
  * Create a unified diff patch between two directories and clean them up.
  *
@@ -269,5 +351,6 @@ module.exports = {
   cleanupOldDiffs,
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
+  updatePropertiesJsonWithVersion,
   diffDirs
 }

package/package.json

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

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

@@ -1692,13 +1692,18 @@ function formatExamples(text) {
       i++
     } else if (isIndented) {
       // Command line — collect all consecutive command lines into one code block
-      // (stops at a blank line or a comment line)
-      result.push('[,bash]')
-      result.push('----')
+      // (stops at a blank line or a comment line). Dedent by the run's minimum
+      // indent rather than trimming each line, so multi-line commands with
+      // backslash continuations keep their relative indentation.
+      const run = []
       while (i < lines.length && /^\s{2,}\S/.test(lines[i]) && !lines[i].trim().startsWith('#')) {
-        result.push(lines[i].trim())
+        run.push(lines[i])
         i++
       }
+      const minIndent = Math.min(...run.map(l => l.match(/^\s*/)[0].length))
+      result.push('[,bash]')
+      result.push('----')
+      run.forEach(l => result.push(l.slice(minIndent)))
       result.push('----')
     } else if (/^\s*`rpk .+`\s*$/.test(line)) {
       // Inline backticked command on its own line - convert to code block

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

@@ -14,7 +14,7 @@ const { validateDirectory, formatResults } = require('./validate-output')
 /**
  * Known rpk plugins that are managed separately (have install/uninstall commands)
  */
-const KNOWN_PLUGINS = ['ai', 'check', 'connect', 'oxla']
+const KNOWN_PLUGINS = ['ai', 'check', 'connect', 'k8s', 'oxla']
 
 /**
  * Parse Go version from 'go version' output
@@ -497,6 +497,13 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
         } else if (stderr.includes('unknown command') || stderr.includes('Error: unknown command')) {
           console.log(`    - ${plugin} is not an installable plugin`)
         } else {
+          // A failed install is non-fatal: generation continues, but this
+          // plugin's commands will be absent from the tree. Expected for `k8s`
+          // during the 26.2 beta window — `rpk k8s install` finds no `latest`
+          // release because the plugin publisher's stableVersionRe only promotes
+          // pure X.Y.Z versions, so k8s commands only appear at GA. A pre-GA
+          // regen that omits `rpk k8s` pages is this, not a generator bug.
+          // See redpanda-data/docs#1801.
           console.warn(`    ✗ Failed to install ${plugin}: ${stderr || stdout}`)
         }
       }