@redpanda-data/docs-extensions-and-macros 5.53.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
  *
@@ -2930,6 +2967,133 @@ programCli
     runCli(options)
   })
 
+/**
+ * check-build-log
+ *
+ * @description
+ * Check an Antora JSON log (`antora --log-format json`): exit 1 when any
+ * record is at level error or fatal, and, with --min-pages and --site-dir,
+ * when fewer HTML pages were written than expected. Prints a Markdown
+ * summary (counts by level, then the error and warning messages grouped and
+ * deduplicated, with file and line) for $GITHUB_STEP_SUMMARY. Warnings never
+ * fail the check. With --blocking-sources, only errors from those
+ * repositories (or with no source) fail it, so a broken page in another
+ * content source of the playbook is reported without blocking.
+ *
+ * @why
+ * Antora's --log-failure-level fails the build but explains nothing in a job
+ * summary, and cannot catch a build that exits 0 having written no files,
+ * which is what Antora does on an unsupported Node version. The Connect docs
+ * PR check runs Antora with --log-failure-level=fatal so this command, not
+ * Antora, decides.
+ *
+ * @example
+ * npx antora --log-format json --log-failure-level=fatal antora-playbook.yml > build.ndjson
+ * npx doc-tools check-build-log build.ndjson --site-dir build/site/connect --min-pages 400 >> "$GITHUB_STEP_SUMMARY"
+ *
+ * # Block only on errors from these repositories; list the rest
+ * npx doc-tools check-build-log build.ndjson --blocking-sources redpanda-data/rp-connect-docs,redpanda-data/connect
+ */
+programCli
+  .command('check-build-log')
+  .description('Check an Antora JSON build log: fail on error or fatal records or too few pages, print a Markdown summary')
+  .argument('<log>', 'Antora log written with --log-format json (one JSON record per line)')
+  .option('--site-dir <dir>', 'Output directory to count HTML pages in (with --min-pages)')
+  .option('--min-pages <n>', 'Fail when fewer than <n> HTML pages were written under --site-dir')
+  .option('--blocking-sources <repos>', 'Comma-separated owner/name repositories whose errors block (default: all). Errors with no source always block; others are listed only')
+  .option('--format <format>', 'Output format: markdown or json', 'markdown')
+  .option('--output <path>', 'Also write the output to this file')
+  .action((log, options) => {
+    const { runCli } = require('../tools/connect-docs/check-build-log')
+    runCli(log, options)
+  })
+
+/**
+ * check-rendered-html
+ *
+ * @description
+ * Scan the rendered HTML of one or more Antora component paths for AsciiDoc
+ * that did not convert: literal backticks outside code, literal `xref:` or
+ * `include::` text, leftover {page-*} or {env-*} attribute references, `|===`
+ * table markup, Asciidoctor's "Unresolved include directive" text, links with
+ * the `unresolved` class, and empty sections (a heading followed directly by a
+ * heading of the same or higher level). Also checks links: a fragment with no
+ * matching id on its target page (broken-anchor), and a relative or
+ * root-relative link under a link root that is not in the build
+ * (broken-link). External links are ignored; links outside every link root,
+ * or into a root the build does not contain, are counted as unchecked. Only
+ * the page body is scanned. Reports findings per page and exits 0 unless
+ * --strict.
+ *
+ * With --changed-pages, findings are split into those on the listed pages and
+ * the rest, and --strict exits 1 only when a listed page has findings, so
+ * defects already on the base never fail a PR.
+ *
+ * @why
+ * These defects reach readers without a single line in the Antora log: two
+ * backticks for an empty enum option, or a backtick glued to the next word,
+ * render as literal backticks on the published page.
+ *
+ * @example
+ * npx doc-tools check-rendered-html build/site --component connect >> "$GITHUB_STEP_SUMMARY"
+ *
+ * # Fail on any finding
+ * npx doc-tools check-rendered-html build/site --strict
+ *
+ * # Self-managed and Cloud Connect pages; fail only on the pages a PR changed
+ * npx doc-tools check-rendered-html build/site --component connect,cloud-data-platform/develop/connect \
+ *   --changed-pages changed-pages.txt --strict
+ */
+programCli
+  .command('check-rendered-html')
+  .description('Scan rendered Antora HTML for unconverted AsciiDoc (literal backticks, xref:, include::, attributes, tables, empty sections) and broken anchors and links')
+  .argument('<site-dir>', 'Antora output directory (the --to-dir of the build)')
+  .option('--component <path>', 'Component output path to scan under <site-dir>; repeat it or give a comma list, for example connect,cloud-data-platform/develop/connect (default: connect)', (value, previous = []) => previous.concat(value))
+  .option('--link-root <path>', 'Site path whose linked pages must exist; repeat it or give a comma list. Scanned components are always included. Links outside every root, or into a root not in the build, are counted as unchecked (default: connect,cloud-data-platform/develop/connect)', (value, previous = []) => previous.concat(value))
+  .option('--pages <file>', 'Only scan the pages listed in <file>, one path relative to <site-dir> per line')
+  .option('--changed-pages <file>', 'Pages a PR changed: one path relative to <site-dir> per line (the sitePath from connect-docs-diff) or connect-docs-diff --format json output. All pages are still scanned; findings are split into changed and other pages, and --strict fails only on changed pages')
+  .option('--format <format>', 'Output format: markdown or json', 'markdown')
+  .option('--output <path>', 'Also write the output to this file')
+  .option('--strict', 'Exit 1 when any finding exists, or with --changed-pages when a changed page has findings (default: always exit 0)')
+  .action((siteDir, options) => {
+    const { runCli } = require('../tools/connect-docs/check-rendered-html')
+    runCli(siteDir, options)
+  })
+
+/**
+ * connect-docs-diff
+ *
+ * @description
+ * Compare two trees written by connect's docs generator, for example a PR's
+ * merge base and its head, and map each added, removed, or changed partial or
+ * example to the docs.redpanda.com page that includes it. Prints a Markdown
+ * table of changed pages with links, then a unified diff per file in
+ * collapsible blocks, capped in size. A tree root can be connect's docs/
+ * directory, its modules/ directory, or the components/ directory.
+ *
+ * @why
+ * Writers review Go string literals today and never see the page. The
+ * generated output is the published change: connect strings, benthos strings
+ * from a go.mod bump, and generator changes all show up here.
+ *
+ * @example
+ * npx doc-tools connect-docs-diff base/modules head/modules >> "$GITHUB_STEP_SUMMARY"
+ * npx doc-tools connect-docs-diff base/modules head/modules --format json
+ */
+programCli
+  .command('connect-docs-diff')
+  .description('Diff two generated Connect docs trees and map each changed partial or example to its published page')
+  .argument('<base-dir>', 'Generated tree of the base (merge base) commit')
+  .argument('<head-dir>', 'Generated tree of the head commit')
+  .option('--format <format>', 'Output format: markdown or json', 'markdown')
+  .option('--site-url <url>', 'Docs site the page links point at', 'https://docs.redpanda.com')
+  .option('--max-bytes <n>', 'Cap on the Markdown output size; diffs past it are counted, not shown', '60000')
+  .option('--output <path>', 'Also write the output to this file')
+  .action((baseDir, headDir, options) => {
+    const { runCli } = require('../tools/connect-docs/diff-generated')
+    runCli(baseDir, headDir, options)
+  })
+
 /**
  * preview-string
  *
@@ -3009,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