@redpanda-data/docs-extensions-and-macros 5.3.1 → 5.3.3

package/bin/doc-tools.js

@@ -27,7 +27,8 @@ const {
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
   updatePropertiesJsonWithVersion,
-  cleanupOldDiffs
+  cleanupOldDiffs,
+  resolveDiffBaseline
 } = require('../cli-utils/diff-utils')
 
 // Import other utilities
@@ -890,6 +891,7 @@ automation
   .option('-t, --tag <tag>', 'Git tag for released content (GA/beta)')
   .option('-b, --branch <branch>', 'Branch name for in-progress content')
   .option('--diff <oldTag>', 'Diff properties against <oldTag> and restore removed deprecated properties. Recommended for accurate output; falls back to latest-redpanda-tag from antora.yml if not specified')
+  .option('--regenerate-old-baseline', 'Re-extract the --diff tag from source instead of using the committed attachments/redpanda-properties-<oldTag>.json baseline')
   .option('--overrides <path>', 'Optional JSON file with property description overrides', 'docs-data/property-overrides.json')
   .option('--output-dir <dir>', 'Where to write all generated files', 'modules/reference')
   .option('--cloud-support', 'Add AsciiDoc tags to generated property docs to indicate which ones are supported in Redpanda Cloud. This data is fetched from the cloudv2 repository so requires a GitHub token with repo permissions. Set the token as an environment variable using GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN', true)
@@ -982,7 +984,13 @@ automation
     // When a diff is needed, skip AsciiDoc generation during extraction so we
     // can merge removed deprecated properties first and generate only once.
     if (needsDiff) {
-      make(oldTag, overridesPath, templates, outputDir, { skipPartials: true })
+      const { useCommitted, baselinePath } = resolveDiffBaseline(outputDir, oldTag, options.regenerateOldBaseline)
+      if (useCommitted) {
+        console.log(`Using committed baseline for ${oldTag}: ${baselinePath}`)
+        console.log('   Pass --regenerate-old-baseline to rebuild it from source instead.')
+      } else {
+        make(oldTag, overridesPath, templates, outputDir, { skipPartials: true })
+      }
       make(newTag, overridesPath, templates, outputDir, { skipPartials: true })
     } else {
       make(newTag, overridesPath, templates, outputDir)
@@ -992,7 +1000,16 @@ automation
     // the new JSON so they appear in the generated documentation.
     if (needsDiff) {
       const diffOutputDir = overridesPath ? path.dirname(path.resolve(overridesPath)) : outputDir
-      generatePropertyComparisonReport(oldTag, newTag, diffOutputDir)
+      try {
+        generatePropertyComparisonReport(oldTag, newTag, diffOutputDir)
+      } catch (err) {
+        // A missing baseline only warns inside generatePropertyComparisonReport.
+        // Reaching this catch means both inputs existed and the comparison
+        // itself failed, so fail the run: continuing would silently drop
+        // removed-deprecated restoration and "Introduced in" version stamping.
+        console.error(`Error: Property comparison failed: ${err.message}`)
+        process.exit(1)
+      }
 
       try {
         const diffReportPath = path.join(diffOutputDir, `redpanda-property-changes-${oldTag}-to-${newTag}.json`)
@@ -1012,7 +1029,11 @@ automation
           }
         }
       } catch (err) {
-        console.warn(`Warning: Failed to generate PR summary: ${err.message}`)
+        // The diff report exists but could not be read or applied. Fail the
+        // run rather than shipping docs that are missing removed-deprecated
+        // restoration or version stamps.
+        console.error(`Error: Failed to process the property diff report: ${err.message}`)
+        process.exit(1)
       }
 
       cleanupOldDiffs(diffOutputDir)
@@ -1040,15 +1061,32 @@ automation
 
       try {
         const jsonDir = path.resolve(outputDir, 'attachments')
+        // Invariant: always retain the comparison pair this run actually used
+        // (the current tag's JSON and the diff baseline's JSON) in addition to
+        // the 2 newest versioned JSONs. A backport run can compare tags that
+        // are not the 2 newest, and the next run's comparison needs its
+        // baseline JSON to survive. Mirrors the retention in
+        // tools/property-extractor/Makefile (generate-docs cleanup).
+        const parseVersion = f => f.match(/^redpanda-properties-v([\d.]+)\.json$/)[1].split('.').map(Number)
+        const byVersionDesc = (a, b) => {
+          const [va, vb] = [parseVersion(a), parseVersion(b)]
+          for (let i = 0; i < Math.max(va.length, vb.length); i++) {
+            if ((vb[i] || 0) !== (va[i] || 0)) return (vb[i] || 0) - (va[i] || 0)
+          }
+          return 0
+        }
         const propertyFiles = fs.readdirSync(jsonDir)
           .filter(f => /^redpanda-properties-v[\d.]+\.json$/.test(f))
-          .sort()
+          .sort(byVersionDesc)
 
-        const keepFile = `redpanda-properties-${newTag}.json`
-        const filesToDelete = propertyFiles.filter(f => f !== keepFile)
+        const filesToKeep = new Set(propertyFiles.slice(0, 2))
+        for (const tag of [newTag, oldTag]) {
+          if (tag) filesToKeep.add(`redpanda-properties-${tag}.json`)
+        }
+        const filesToDelete = propertyFiles.filter(f => !filesToKeep.has(f))
 
         if (filesToDelete.length > 0) {
-          console.log('🧹 Cleaning up old property JSON files...')
+          console.log('🧹 Cleaning up old property JSON files (keeping the 2 newest plus the comparison pair)...')
           filesToDelete.forEach(file => {
             fs.unlinkSync(path.join(jsonDir, file))
             console.log(`   Deleted: ${file}`)

package/cli-utils/diff-utils.js

@@ -65,9 +65,16 @@ function cleanupOldDiffs (diffDir) {
 /**
  * Generate a detailed JSON report describing property changes between two releases.
  *
+ * When either input JSON is missing the comparison is skipped with a warning
+ * (a genuinely new oldest tag legitimately has no baseline). When both inputs
+ * exist but the comparison itself fails, this throws so callers fail loudly
+ * instead of silently dropping removed-deprecated restoration and version
+ * stamping.
+ *
  * @param {string} oldTag - Release tag or identifier for the "old" properties set.
  * @param {string} newTag - Release tag or identifier for the "new" properties set.
  * @param {string} outputDir - Directory where the comparison report will be written.
+ * @throws {Error} When both input JSONs exist but the comparison fails to run or exits non-zero.
  */
 function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
   try {
@@ -81,13 +88,14 @@ function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
 
     if (!fs.existsSync(oldJsonPath)) {
       console.log(`Warning: Old properties JSON not found at: ${oldJsonPath}`)
-      console.log('   Skipping detailed property comparison.')
+      console.log('   Skipping detailed property comparison: no diff report will be generated, so removed deprecated properties are not restored and new properties are not stamped with "Introduced in" versions.')
+      console.log(`   This is expected only when ${oldTag} has never been extracted (for example, the oldest supported release).`)
       return
     }
 
     if (!fs.existsSync(newJsonPath)) {
       console.log(`Warning: New properties JSON not found at: ${newJsonPath}`)
-      console.log('   Skipping detailed property comparison.')
+      console.log('   Skipping detailed property comparison: no diff report will be generated, so removed deprecated properties are not restored and new properties are not stamped with "Introduced in" versions.')
       return
     }
 
@@ -107,15 +115,19 @@ function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
       cwd: propertyExtractorDir
     })
 
+    // Both inputs exist, so a failed comparison is a hard error: continuing
+    // would silently skip removed-deprecated restoration and version stamping
     if (result.error) {
-      console.error(`Error: Property comparison failed: ${result.error.message}`)
-    } else if (result.status !== 0) {
-      console.error(`Error: Property comparison exited with code: ${result.status}`)
-    } else {
-      console.log(`Done: Property comparison report saved to: ${reportPath}`)
+      throw new Error(`Property comparison failed to run: ${result.error.message}`)
+    }
+    if (result.status !== 0) {
+      throw new Error(`Property comparison exited with code ${result.status}`)
     }
+    console.log(`Done: Property comparison report saved to: ${reportPath}`)
   } catch (error) {
     console.error(`Error: Error generating property comparison: ${error.message}`)
+    // Propagate so callers fail loudly instead of shipping incomplete docs
+    throw error
   }
 }
 
@@ -346,7 +358,30 @@ function diffDirs (kind, oldTag, newTag, oldTempDir, newTempDir) {
   }
 }
 
+/**
+ * Decide whether a committed baseline attachment can serve as the old side of
+ * a property diff. Rebuilding the old tag in place overwrites the committed
+ * attachment with a fresh extraction, so any contamination in that extraction
+ * silently becomes both the stored baseline and the diff input (the diff then
+ * compares the run against its own output and reports no new properties).
+ * @param {string} outputDir - Docs output dir that contains attachments/
+ * @param {string} oldTag - Old version tag (for example, v26.1.14)
+ * @param {boolean} [regenerate=false] - Force re-extraction even if a baseline exists
+ * @returns {{useCommitted: boolean, baselinePath: string}}
+ */
+function resolveDiffBaseline (outputDir, oldTag, regenerate = false) {
+  const attachmentsDir = path.resolve(outputDir, 'attachments')
+  const baselinePath = path.resolve(attachmentsDir, `redpanda-properties-${oldTag}.json`)
+  const relativePath = path.relative(attachmentsDir, baselinePath)
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath) || relativePath.includes(path.sep)) {
+    throw new Error(`Invalid old tag "${oldTag}": baseline must resolve within the attachments directory`)
+  }
+  return { useCommitted: !regenerate && fs.existsSync(baselinePath), baselinePath }
+}
+
 module.exports = {
+  resolveDiffBaseline,
+
   runClusterDocs,
   cleanupOldDiffs,
   generatePropertyComparisonReport,

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.1",
+  "version": "5.3.3",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/property-extractor/Makefile

@@ -72,19 +72,30 @@ clean:
 	@rm -rf $(VENV) $(TMP_ROOT) $(REPO_ROOT)/autogenerated
 
 # --- Clone or update Redpanda, checkout TAG or default branch ---
+# Clones are shallow: the extractor only reads source files at a single tag,
+# so full history is wasted time and disk.
+# Auth is passed as a per-invocation HTTP header (git -c before the clone
+# subcommand), never embedded in the remote URL, so no token is persisted in
+# the clone's .git/config. The clone lives inside the installed package dir,
+# so a persisted token would be readable by anything that can list it.
 redpanda-git:
 	@mkdir -p "$(TMP_ROOT)"
 	@echo "🔄 Cloning/updating Redpanda into $(REDPANDA_SRC)…"
 	@if [ -d "$(REDPANDA_SRC)" ]; then \
-	  git -C "$(REDPANDA_SRC)" fetch --all --tags -q; \
+	  git -C "$(REDPANDA_SRC)" fetch --depth 1 -q origin "+refs/tags/$(TAG):refs/tags/$(TAG)" 2>/dev/null || \
+	    git -C "$(REDPANDA_SRC)" fetch --depth 1 -q origin "+refs/heads/$(TAG):refs/remotes/origin/$(TAG)" 2>/dev/null || \
+	    git -C "$(REDPANDA_SRC)" fetch --all --tags -q; \
 	else \
 	  GH_TOKEN=$${REDPANDA_GITHUB_TOKEN:-$${GITHUB_TOKEN:-$${GH_TOKEN}}}; \
+	  REPO_URL="https://github.com/redpanda-data/redpanda.git"; \
 	  if [ -n "$$GH_TOKEN" ]; then \
 	    echo "🔑 Using authenticated clone (token provided)"; \
-	    git clone -q https://$$GH_TOKEN@github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
+	    AUTH_HEADER="AUTHORIZATION: basic $$(printf '%s' "x-access-token:$$GH_TOKEN" | base64 | tr -d '\n')"; \
 	  else \
-	    git clone -q https://github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
+	    AUTH_HEADER=""; \
 	  fi; \
+	  git -c http.https://github.com/.extraheader="$$AUTH_HEADER" clone -q --depth 1 --branch "$(TAG)" "$$REPO_URL" "$(REDPANDA_SRC)" 2>/dev/null || \
+	    git -c http.https://github.com/.extraheader="$$AUTH_HEADER" clone -q --depth 1 "$$REPO_URL" "$(REDPANDA_SRC)"; \
 	fi; \
 	if git -C "$(REDPANDA_SRC)" rev-parse --verify -q "origin/$(TAG)" >/dev/null 2>&1; then \
 	  echo "🔖 Checking out remote branch 'origin/$(TAG)'"; \
@@ -94,24 +105,44 @@ redpanda-git:
 	  echo "🔖 Checking out '$(TAG)'"; \
 	  git -C "$(REDPANDA_SRC)" checkout -q "$(TAG)"; \
 	else \
-	  DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" symbolic-ref --short refs/remotes/origin/HEAD); \
-	  echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
-	  git -C "$(REDPANDA_SRC)" checkout -q "$${DEFAULT_BRANCH}"; \
+	  DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true); \
+	  if [ -n "$$DEFAULT_BRANCH" ]; then \
+	    echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
+	    git -C "$(REDPANDA_SRC)" checkout -q "$${DEFAULT_BRANCH}"; \
+	  else \
+	    DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" ls-remote --symref origin HEAD | awk '/^ref:/ {sub(/^refs\/heads\//, "", $$2); print $$2; exit}'); \
+	    if [ -z "$$DEFAULT_BRANCH" ]; then \
+	      echo "❌ Tag '$(TAG)' not found and the default branch could not be determined"; \
+	      exit 1; \
+	    fi; \
+	    echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
+	    git -C "$(REDPANDA_SRC)" fetch --depth 1 -q origin "$$DEFAULT_BRANCH"; \
+	    git -C "$(REDPANDA_SRC)" checkout -q FETCH_HEAD; \
+	  fi; \
 	fi
 
 # --- Clone Tree-sitter grammar & generate parser ---
+# Skips npm install and parser generation when the generated output already
+# exists for the pinned grammar version, so repeat builds stay fast
 treesitter:
 	@echo "🌲 Ensuring tree-sitter-cpp grammar…"
 	@if [ ! -d "$(TREESITTER_DIR)/.git" ]; then \
 	  rm -rf "$(TREESITTER_DIR)"; \
 	  git clone https://github.com/tree-sitter/tree-sitter-cpp.git "$(TREESITTER_DIR)"; \
 	fi
-	@echo "🔄 Ensuring tree-sitter-cpp is at compatible version v0.20.5…"
-	@cd "$(TREESITTER_DIR)" && \
-	  git fetch --tags -q && \
-	  git checkout -q v0.20.5
-	@echo "🔧 Generating parser in $(TREESITTER_DIR)…"
-	@cd "$(TREESITTER_DIR)" && export CFLAGS="-Wno-unused-but-set-variable" && npm install --silent && export CFLAGS="-Wno-unused-but-set-variable" && $(TREE_SITTER) generate
+	@CURRENT_TAG=$$(git -C "$(TREESITTER_DIR)" describe --tags --exact-match 2>/dev/null || true); \
+	if [ "$$CURRENT_TAG" = "v0.20.5" ] && [ -f "$(TREESITTER_DIR)/src/parser.c" ]; then \
+	  echo "✅ tree-sitter-cpp parser already generated at v0.20.5; skipping regeneration"; \
+	else \
+	  echo "🔄 Ensuring tree-sitter-cpp is at compatible version v0.20.5…"; \
+	  cd "$(TREESITTER_DIR)" && \
+	    git fetch --tags -q && \
+	    git checkout -q v0.20.5 && \
+	    echo "🔧 Generating parser in $(TREESITTER_DIR)…" && \
+	    export CFLAGS="-Wno-unused-but-set-variable" && \
+	    npm install --silent && \
+	    $(TREE_SITTER) generate; \
+	fi
 
 # --- Install Node.js dependencies for Handlebars ---
 node-deps:
@@ -146,6 +177,9 @@ generate-docs: node-deps
 	else \
 	  echo "   ⚠️  Source file $(TOOL_ROOT)/gen/$(TAG)-properties.json not found, skipping copy"; \
 	fi
+	@# Invariant: keep at least 2 versioned JSONs, the current release plus the
+	@# diff baseline that the next run's comparison depends on. Mirrors the
+	@# retention in bin/doc-tools.js (post-run property JSON cleanup).
 	@echo "🧹 Cleaning up old versioned JSON files (keeping only 2 most recent)…"
 	@cd "$(OUTPUT_JSON_DIR)" && \
 	  ls -t redpanda-properties-*.json 2>/dev/null | tail -n +3 | while read file; do \

package/tools/property-extractor/cloud_config.py

@@ -434,6 +434,22 @@ def fetch_cloud_config(github_token: Optional[str] = None) -> CloudConfig:
         raise CloudConfigError(error_msg) from e
 
 
+def _match_name_or_alias(prop_name: str, prop_data: Dict, cloud_set: Set[str]) -> Optional[str]:
+    """
+    Return the name under which a property appears in a cloud property set.
+
+    Checks the property's own name first, then each entry in its `aliases`
+    array. Returns the matching name, or None when neither the name nor any
+    alias is in the set.
+    """
+    if prop_name in cloud_set:
+        return prop_name
+    for alias in prop_data.get('aliases') or []:
+        if alias in cloud_set:
+            return alias
+    return None
+
+
 def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> Dict:
     """
     Annotate property definitions with cloud-support metadata derived from a CloudConfig.
@@ -492,29 +508,39 @@ def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> D
                 continue
             
             processed_count += 1
-            
+
             # Initialize cloud metadata with defaults
             prop_data['cloud_editable'] = False
             prop_data['cloud_readonly'] = False
             prop_data['cloud_supported'] = False
             prop_data['cloud_byoc_only'] = False
-            
-            # Determine cloud support status
-            if prop_name in editable_props:
+
+            # Determine cloud support status. Match on the property's current
+            # name or any of its aliases, so a property renamed in Redpanda
+            # still picks up cloud metadata when the cloud configuration
+            # references the old name.
+            editable_match = _match_name_or_alias(prop_name, prop_data, editable_props)
+            readonly_match = None if editable_match else _match_name_or_alias(prop_name, prop_data, readonly_props)
+
+            if editable_match:
+                if editable_match != prop_name:
+                    logger.info(f"Property '{prop_name}' matched cloud editable configuration via alias '{editable_match}'")
                 prop_data['cloud_editable'] = True
                 prop_data['cloud_readonly'] = False
                 prop_data['cloud_supported'] = True
                 cloud_supported_count += 1
                 editable_count += 1
-                
-                # Check if BYOC only
-                if cloud_config.is_byoc_only(prop_name):
+
+                # Check if BYOC only, using the name the cloud configuration knows
+                if cloud_config.is_byoc_only(editable_match):
                     prop_data['cloud_byoc_only'] = True
                     byoc_only_count += 1
                 else:
                     prop_data['cloud_byoc_only'] = False
-                    
-            elif prop_name in readonly_props:
+
+            elif readonly_match:
+                if readonly_match != prop_name:
+                    logger.info(f"Property '{prop_name}' matched cloud readonly configuration via alias '{readonly_match}'")
                 prop_data['cloud_editable'] = False
                 prop_data['cloud_readonly'] = True
                 prop_data['cloud_supported'] = True
@@ -565,11 +591,14 @@ def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> D
         logger.warning("  2. Property names don't match between sources")
         logger.warning("  3. All properties are self-managed only")
     
-    # Check for potential mismatches
-    unmatched_cloud_props = (editable_props | readonly_props) - {
-        name for name, data in properties.items() 
-        if isinstance(data, dict) and data.get('config_scope') in ['cluster', 'broker', 'topic']
-    }
+    # Check for potential mismatches, counting aliases as known names so a
+    # renamed property does not show up as missing
+    extracted_cloud_names = set()
+    for name, data in properties.items():
+        if isinstance(data, dict) and data.get('config_scope') in ['cluster', 'broker', 'topic']:
+            extracted_cloud_names.add(name)
+            extracted_cloud_names.update(data.get('aliases') or [])
+    unmatched_cloud_props = (editable_props | readonly_props) - extracted_cloud_names
     
     if unmatched_cloud_props:
         logger.info(f"Cloud configuration contains {len(unmatched_cloud_props)} properties not found in extracted properties:")

package/tools/property-extractor/compare-properties.js

@@ -364,8 +364,10 @@ function generateConsoleReport(report, oldVersion, newVersion) {
 /**
  * Write a structured JSON comparison report to disk.
  *
- * Produces a JSON file containing a comparison header (old/new versions and timestamp),
+ * Produces a JSON file containing a comparison header (old/new versions),
  * a summary with counts for each change category, and the full details object passed as `report`.
+ * The report is deterministic: rerunning the comparison on the same inputs
+ * produces byte-identical output, so committed reports do not churn.
  *
  * @param {Object} report - Comparison details object produced by compareProperties; expected to contain arrays: `newProperties`, `changedDefaults`, `changedDescriptions`, `changedTypes`, `deprecatedProperties`, `removedProperties`, and `emptyDescriptions`.
  * @param {string} oldVersion - The previous version identifier included in the comparison header.
@@ -376,8 +378,7 @@ function generateJsonReport(report, oldVersion, newVersion, outputPath) {
   const jsonReport = {
     comparison: {
       oldVersion,
-      newVersion,
-      timestamp: new Date().toISOString()
+      newVersion
     },
     summary: {
       newProperties: report.newProperties.length,

package/tools/property-extractor/pr-summary-formatter.js

@@ -20,7 +20,7 @@
  *
  * Input format (diff data from compare-properties.js):
  *   {
- *     comparison: { oldVersion, newVersion, timestamp },
+ *     comparison: { oldVersion, newVersion },
  *     summary: { newProperties, changedDefaults, ... },
  *     details: { newProperties: [...], changedDefaults: [...], ... }
  *   }
@@ -278,11 +278,14 @@ function generatePRSummary(diffData) {
   lines.push('</details>');
   lines.push('');
 
-  // Footer
+  // Footer. The timestamp only appears in reports generated before the
+  // field was removed to keep committed diff reports deterministic.
   lines.push('---');
   lines.push('');
-  lines.push(`*Generated: ${diffData.comparison.timestamp}*`);
-  lines.push('');
+  if (diffData.comparison.timestamp) {
+    lines.push(`*Generated: ${diffData.comparison.timestamp}*`);
+    lines.push('');
+  }
   lines.push('<!-- PR_SUMMARY_END -->');
 
   return lines.join('\n');

package/tools/property-extractor/property_extractor.py

@@ -321,16 +321,35 @@ _constexpr_cache = ConstexprCache()
 _type_definitions_cache = {}
 
 # Import topic property extractor
+# Set from --path in main() so every consumer of the Redpanda source uses the
+# tree the caller pointed at, regardless of the current working directory. The
+# hardcoded search below is only a fallback for direct module use.
+_redpanda_source_override = None
+
+
+def set_redpanda_source(path):
+    """Record the Redpanda source directory passed via --path."""
+    global _redpanda_source_override
+    _redpanda_source_override = path
+
+
 def find_redpanda_source():
     """
-    Locate the Redpanda source directory by searching standard locations.
-    
-    The property extractor looks for the Redpanda source code in multiple
-    locations to handle different execution contexts (project root, tools directory, etc.).
-    
+    Locate the Redpanda source directory.
+
+    Prefers the path passed via --path (recorded by set_redpanda_source);
+    falls back to searching standard locations relative to the current
+    working directory. Before this preference existed, running the extractor
+    from any directory that did not match a hardcoded guess silently
+    disabled the ConstantResolver: no validator enums, no enterprise enum
+    metadata, no constexpr resolution, with only a debug-level log line.
+
     Returns:
         str or None: Path to the Redpanda source directory if found, None otherwise.
     """
+    if _redpanda_source_override and os.path.exists(_redpanda_source_override):
+        return _redpanda_source_override
+
     redpanda_source_paths = [
         'tmp/redpanda',  # Current directory
         '../tmp/redpanda',  # Parent directory  
@@ -725,6 +744,13 @@ def transform_files_with_properties(files_with_properties):
         if src_v_path.exists():
             constant_resolver = ConstantResolver(src_v_path)
             logger.debug(f"Initialized ConstantResolver with path: {src_v_path}")
+    if constant_resolver is None:
+        logger.warning(
+            "Redpanda source directory not found: validator enum extraction "
+            "and enterprise enum metadata are DISABLED for this run. "
+            "Properties like sasl_mechanisms will be missing items.enum and "
+            "x-enum-metadata. Pass --path to the Redpanda checkout to fix this."
+        )
 
     transformers = [
         EnterpriseTransformer(), ## this must be the first, as it modifies current data
@@ -942,6 +968,32 @@ def merge_properties_and_definitions(properties, definitions):
     return dict(properties=properties, definitions=definitions)
 
 
+# Phantom stub entries created by apply_property_overrides during the current
+# run. An entry is recorded whenever an override key matches no extracted
+# property and a placeholder doc entry is fabricated from the override alone.
+# Tracked at module level so the run summary in main() can report them all in
+# one place at the end of the run.
+phantom_stub_entries = []
+
+
+def report_phantom_stubs():
+    """Log one prominent warning block listing every phantom stub created from overrides."""
+    if not phantom_stub_entries:
+        return
+    logger.warning("=" * 70)
+    logger.warning(
+        f"⚠️  {len(phantom_stub_entries)} override "
+        f"{'entry' if len(phantom_stub_entries) == 1 else 'entries'} matched no extracted property"
+    )
+    for entry in phantom_stub_entries:
+        logger.warning(
+            f"Override key '{entry['name']}' matched no extracted property — created a stub entry "
+            f"with config_scope '{entry['config_scope']}'. If the property was renamed or removed, "
+            f"update docs-data/property-overrides.json."
+        )
+    logger.warning("=" * 70)
+
+
 def apply_property_overrides(properties, overrides, overrides_file_path=None):
     """
     Apply overrides from an overrides mapping to the extracted properties, mutating and returning the properties dictionary.
@@ -961,6 +1013,7 @@ def apply_property_overrides(properties, overrides, overrides_file_path=None):
     Returns:
         dict: The same properties mapping with overrides applied and any new properties created.
     """
+    phantom_stub_entries.clear()
     if overrides and "properties" in overrides:
         for prop, override in overrides["properties"].items():
             # First check if property exists by key
@@ -982,7 +1035,13 @@ def apply_property_overrides(properties, overrides, overrides_file_path=None):
                 else:
                     # Create new property from override
                     logger.info(f"Creating new property from override: {prop}")
-                    properties[prop] = _create_property_from_override(prop, override, overrides_file_path)
+                    new_property = _create_property_from_override(prop, override, overrides_file_path)
+                    properties[prop] = new_property
+                    # Record the phantom stub so the run summary can flag it loudly
+                    phantom_stub_entries.append({
+                        "name": prop,
+                        "config_scope": new_property.get("config_scope"),
+                    })
     return properties
 
 
@@ -2876,6 +2935,11 @@ def main():
         treesitter_dir, destination_path
     )
 
+    # Every consumer of the Redpanda source (ConstantResolver, constexpr
+    # fallback search) must use the tree the caller pointed at, not a
+    # cwd-relative guess.
+    set_redpanda_source(options.path)
+
     # Pre-build constexpr cache for performance
     # This avoids repeated filesystem walks when resolving C++ identifiers and function calls
     logger.info("🔧 Building constexpr identifier cache...")
@@ -3073,5 +3137,16 @@ def main():
             logging.error(f"Failed to write enhanced output file: {e}")
             sys.exit(1)
 
+    # Surface phantom stubs prominently at the end of the run. These are
+    # override keys that matched no extracted property, so a placeholder doc
+    # entry was fabricated from the override alone.
+    if phantom_stub_entries:
+        report_phantom_stubs()
+        phantom_names = ", ".join(entry["name"] for entry in phantom_stub_entries)
+        print(
+            f"⚠️  Phantom stub entries created from overrides: "
+            f"{len(phantom_stub_entries)} ({phantom_names})"
+        )
+
 if __name__ == "__main__":
     main()

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}}

package/tools/property-extractor/templates/property-backup.hbs

@@ -1,161 +0,0 @@
-{{#if category}}
-// tag::category-{{category}}[]
-{{/if}}
-{{#if exclude_from_docs}}
-// tag::exclude-from-docs[]
-{{/if}}
-{{#if is_deprecated}}
-// tag::deprecated[]
-{{/if}}
-{{#if cloud_supported}}
-// tag::redpanda-cloud[]
-{{/if}}
-=== {{name}}
-{{#if version}}
-
-ifndef::env-cloud[]
-*Introduced in {{version}}*
-endif::[]
-{{/if}}
-{{#if description}}
-
-{{{description}}}
-{{else}}
-
-No description available.
-
-{{/if}}
-{{#if is_enterprise}}
-
-ifndef::env-cloud[]
-*Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
-endif::[]
-{{/if}}
-{{#if cloud_byoc_only}}
-
-ifdef::env-cloud[]
-NOTE: This property is available only in Redpanda Cloud BYOC deployments.
-endif::[]
-
-{{/if}}
-{{#if units}}
-
-*Unit:* {{units}}
-{{else}}
-{{#if (formatUnits name)}}
-
-*Unit:* {{formatUnits name}}
-{{/if}}
-{{/if}}
-{{#if (ne defined_in "src/v/config/node_config.cc")}}
-{{#if (ne needs_restart undefined)}}
-
-*Requires restart:* {{#if needs_restart}}Yes{{else}}No{{/if}}
-{{/if}}
-{{/if}}
-
-ifndef::env-cloud[]
-*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
-endif::[]
-{{#if visibility}}
-
-// tag::self-managed-only[]
-*Visibility:* `{{visibility}}`
-// end::self-managed-only[]
-{{/if}}
-{{#if type}}
-
-*Type:* {{type}}
-{{/if}}
-{{#if (and minimum maximum)}}
-
-*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
-{{else}}
-{{#if minimum}}
-
-*Minimum value:* `{{minimum}}`
-{{/if}}
-{{#if maximum}}
-
-*Maximum value:* `{{maximum}}`
-{{/if}}
-{{/if}}
-{{#if (ne default undefined)}}
-
-ifdef::env-cloud[]
-*Default:* Available in the Redpanda Cloud Console
-endif::[]
-ifndef::env-cloud[]
-*Default:* `{{formatPropertyValue default type}}`
-endif::[]
-{{/if}}
-
-*Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
-{{#if example}}
-
-{{{renderPropertyExample this}}}
-{{/if}}
-{{#if related_topics}}
-{{#with (allTopicsConditional related_topics) as |sectionType|}}
-
-{{#if (eq sectionType "cloud")}}
-ifdef::env-cloud[]
-*Related topics:*
-
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
-{{/each}}
-endif::[]
-{{else if (eq sectionType "self-managed")}}
-ifndef::env-cloud[]
-*Related topics:*
-
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
-{{/each}}
-endif::[]
-{{else}}
-*Related topics:*
-
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{#if (eq type "cloud")}}
-ifdef::env-cloud[]
-* {{{value}}}
-endif::[]
-{{else if (eq type "self-managed")}}
-ifndef::env-cloud[]
-* {{{value}}}
-endif::[]
-{{else}}
-* {{{value}}}
-{{/if}}
-{{/with}}
-{{/each}}
-{{/if}}
-{{/with}}
-{{/if}}
-{{#if aliases}}
-
-// tag::self-managed-only[]
-*Aliases:* {{join aliases ", "}}
-// end::self-managed-only[]
-{{/if}}
-
----
-{{#if cloud_supported}}
-// end::redpanda-cloud[]
-{{/if}}
-{{#if is_deprecated}}
-// end::deprecated[]
-{{/if}}
-{{#if exclude_from_docs}}
-// end::exclude-from-docs[]
-{{/if}}
-{{#if category}}
-// end::category-{{category}}[]
-{{/if}}

package/tools/property-extractor/templates/topic-property-backup.hbs

@@ -1,148 +0,0 @@
-{{#if category}}
-// tag::category-{{category}}[]
-{{/if}}
-{{#if exclude_from_docs}}
-// tag::exclude-from-docs[]
-{{/if}}
-{{#if is_deprecated}}
-// tag::deprecated[]
-{{/if}}
-{{#if cloud_supported}}
-// tag::redpanda-cloud[]
-{{/if}}
-=== {{name}}
-{{#if version}}
-
-*Introduced in {{version}}*
-{{/if}}
-{{#if description}}
-
-{{{description}}}
-{{else}}
-
-No description available.
-{{/if}}
-{{#if is_enterprise}}
-
-ifndef::env-cloud[]
-*Enterprise license required*: `{{enterprise_value}}` (for license details, see xref:get-started:licensing/index.adoc[Redpanda Licensing])
-endif::[]
-{{/if}}
-{{#if cloud_byoc_only}}
-ifdef::env-cloud[]
-NOTE: This property is only available in Redpanda Cloud BYOC deployments.
-endif::[]
-{{/if}}
-{{#if type}}
-
-*Type:* {{type}}
-{{/if}}
-{{#if acceptable_values}}
-
-*Accepted values:* {{{acceptable_values}}}
-{{/if}}
-{{#if corresponding_cluster_property}}
-
-*Related cluster property:* xref:reference:cluster-properties.adoc#{{corresponding_cluster_property}}[{{corresponding_cluster_property}}]
-{{/if}}
-{{#if (and minimum maximum)}}
-
-*Accepted values:* [`{{minimum}}`, `{{maximum}}`]
-{{else}}
-{{#if minimum}}
-
-*Minimum value:* `{{minimum}}`
-{{/if}}
-{{#if maximum}}
-
-*Maximum value:* `{{maximum}}`
-{{/if}}
-{{/if}}
-{{#if (ne default undefined)}}
-{{#if cloud_supported}}
-
-ifdef::env-cloud[]
-*Default:* Available in the Redpanda Cloud Console
-endif::[]
-ifndef::env-cloud[]
-*Default:* `{{formatPropertyValue default type}}`
-endif::[]
-{{else}}
-
-*Default:* `{{formatPropertyValue default type}}`
-{{/if}}
-{{/if}}
-
-*Nullable:* {{#if nullable}}Yes{{else}}No{{/if}}
-
-ifndef::env-cloud[]
-*Restored during xref:manage:whole-cluster-restore.adoc[Whole Cluster Restore]:* {{#if (ne gets_restored false)}}Yes{{else}}No{{/if}}
-endif::[]
-{{#if example}}
-
-{{{renderPropertyExample this}}}
-{{/if}}
-{{#if related_topics}}
-{{#with (allTopicsConditional related_topics) as |sectionType|}}
-
-{{#if (eq sectionType "cloud")}}
-ifdef::env-cloud[]
-*Related topics:*
-
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
-{{/each}}
-endif::[]
-{{else if (eq sectionType "self-managed")}}
-ifndef::env-cloud[]
-*Related topics:*
-
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
-{{/each}}
-endif::[]
-{{else}}
-*Related topics:*
-
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{#if (eq type "cloud")}}
-ifdef::env-cloud[]
-* {{{value}}}
-endif::[]
-{{else if (eq type "self-managed")}}
-ifndef::env-cloud[]
-* {{{value}}}
-endif::[]
-{{else}}
-* {{{value}}}
-{{/if}}
-{{/with}}
-{{/each}}
-{{/if}}
-{{/with}}
-{{/if}}
-{{#if aliases}}
-
-// tag::self-managed-only[]
-*Aliases:* {{join aliases ", "}}
-// end::self-managed-only[]
-{{/if}}
-
----
-{{#if cloud_supported}}
-// end::redpanda-cloud[]
-{{/if}}
-{{#if is_deprecated}}
-// end::deprecated[]
-{{/if}}
-{{#if exclude_from_docs}}
-// end::exclude-from-docs[]
-{{/if}}
-{{#if category}}
-// end::category-{{category}}[]
-{{/if}}