@redpanda-data/docs-extensions-and-macros 5.2.5 → 5.3.0

package/bin/doc-tools.js

@@ -1109,6 +1109,17 @@ automation
   .option('-r, --ref <ref>', 'Git branch or tag to document (e.g., dev, v26.2.0). Clones from GitHub.')
   .option('--from-source <path>', 'Path to local rpk source (src/go/rpk directory)')
   .option('--from-json <path>', 'Regenerate docs from an existing versioned JSON file (skips building)')
+  .option('--plugin <name>', 'Refresh a single rpk plugin\'s docs (ai, connect, k8s, check). Requires --from-json. Installs the plugin, splices its fresh subtree into the snapshot, and re-renders.')
+  .option('--plugin-version <version>', 'Plugin version to install and record (for example, 4.102.0). Defaults to the latest published version.')
+  .option('--plugin-pin <name=version>', 'Pin a plugin version for the installs during full generation (repeatable, for example --plugin-pin k8s=26.3.1-beta.1). Required for pre-GA plugins with no promoted latest version.', (value, pins) => {
+    const eq = value.indexOf('=')
+    if (eq < 1 || eq === value.length - 1) {
+      throw new Error(`Invalid --plugin-pin '${value}': expected <name>=<version>`)
+    }
+    pins[value.slice(0, eq)] = value.slice(eq + 1)
+    return pins
+  }, {})
+  .option('--rpk-bin <path>', 'Path to an existing rpk binary for the plugin refresh (skips download/build)')
   .option('--overrides <path>', 'Path to overrides JSON file', 'docs-data/rpk-overrides.json')
   .option('--diff <oldVersion>', 'Generate diff against previous version')
   .option('--update-whats-new [path]', 'Update what\'s-new file with rpk changes from diff (default: modules/get-started/pages/release-notes/redpanda.adoc)')
@@ -1124,6 +1135,12 @@ automation
     try {
       const { handleRpkDocsGeneration } = require('../tools/rpk-docs/rpk-docs-handler.js')
 
+      if (options.plugin && !options.fromJson) {
+        console.error('Error: --plugin requires --from-json <snapshot>')
+        console.error('A plugin refresh splices the fresh subtree into an existing committed snapshot.')
+        process.exit(1)
+      }
+
       // Handle --update-whats-new with optional path
       let whatsNewPath = null
       if (options.updateWhatsNew !== undefined) {
@@ -1137,6 +1154,10 @@ automation
         ref: options.ref,
         fromSource: options.fromSource,
         fromJson: options.fromJson,
+        plugin: options.plugin,
+        pluginVersion: options.pluginVersion,
+        pluginPins: options.pluginPin,
+        rpkBin: options.rpkBin,
         overrides: options.overrides,
         diff: options.diff,
         updateWhatsNew: whatsNewPath,
@@ -1150,6 +1171,10 @@ automation
       })
 
       if (result.success) {
+        if (result.skipped) {
+          console.log(`\n✓ Skipped: ${result.reason}`)
+          process.exit(0)
+        }
         console.log('\n✓ rpk documentation generated successfully')
 
         // Write PR summary to file if requested (useful for GitHub Actions)
@@ -1175,6 +1200,140 @@ automation
     }
   })
 
+/**
+ * generate rpk-plugin-stubs
+ *
+ * @description
+ * Reconciles a consumer repo's single-source stub pages and nav section
+ * against the rpk plugin partials generated in the docs repo. Run from the
+ * consumer repo root (for example, adp-docs for rpk ai). Creates stubs for
+ * new partials, deletes managed stubs whose partial is gone, rebuilds the
+ * plugin's nav block, and proposes page aliases for likely renames.
+ * Full reconcile, so it is idempotent and heals pre-existing drift.
+ */
+automation
+  .command('rpk-plugin-stubs')
+  .description('Reconcile single-source stub pages and nav against the docs repo\'s rpk plugin partials. Run from the consumer repo root.')
+  .option('--plugin <name>', 'rpk plugin command name', 'ai')
+  .option('--docs-repo <owner/repo>', 'Docs repo that owns the partials', 'redpanda-data/docs')
+  .option('--docs-ref <ref>', 'Branch or tag to read partials from', 'main')
+  .option('--partials-dir <path>', 'Local partials directory (skips cloning the docs repo)')
+  .option('--source-path <path>', 'Path in the docs repo to read from (default: modules/reference/partials/rpk-<plugin>; use modules/reference/pages/rpk/rpk-connect for page-family content)')
+  .option('--stub-dir <path>', 'Stub pages directory in the consumer repo (default: modules/reference/pages/rpk/rpk-<plugin>)')
+  .option('--nav-file <path>', 'Nav file whose plugin block is rebuilt', 'modules/ROOT/nav.adoc')
+  .option('--include-prefix <prefix>', 'Antora resource prefix for stub includes. Default: inferred from an existing stub.')
+  .option('--attribute <line>', 'Page attribute line added to new stubs (repeatable)', (value, acc) => { acc.push(value); return acc }, [])
+  .option('--summary-file <path>', 'Write a markdown summary (for PR bodies)')
+  .option('--dry-run', 'Report what would change without writing')
+  .action(async (options) => {
+    try {
+      const {
+        readPartialTitles, fetchPartialsDir, inferIncludePrefix, reconcileStubs
+      } = require('../tools/rpk-docs/generate-plugin-stubs.js')
+
+      const plugin = options.plugin
+      const stubDir = options.stubDir || `modules/reference/pages/rpk/rpk-${plugin}`
+      const partialsDir = options.partialsDir || fetchPartialsDir({
+        docsRepo: options.docsRepo,
+        docsRef: options.docsRef,
+        plugin,
+        sourcePath: options.sourcePath
+      })
+
+      const includePrefix = options.includePrefix || inferIncludePrefix(stubDir, plugin)
+      if (!includePrefix) {
+        console.error('Error: could not infer the include prefix (no existing stubs). Pass --include-prefix, for example: streaming:reference:partial$rpk-ai/')
+        process.exit(1)
+      }
+
+      const partials = readPartialTitles(partialsDir)
+      console.log(`Reconciling ${partials.length} partial(s) against ${stubDir}`)
+
+      const result = reconcileStubs({
+        partials,
+        stubDir,
+        navFile: options.navFile,
+        plugin,
+        includePrefix,
+        ...(options.attribute.length > 0 ? { attributes: options.attribute } : {}),
+        dryRun: options.dryRun
+      })
+
+      console.log(`  Created: ${result.created.length}, deleted: ${result.deleted.length}, nav updated: ${result.navUpdated}`)
+      for (const f of result.created) console.log(`  + ${f}`)
+      for (const f of result.deleted) console.log(`  - ${f}`)
+      for (const f of result.keptNonStub) console.log(`  ! kept (not a managed stub): ${f}`)
+
+      const lines = []
+      lines.push(`## rpk ${plugin} stub reconciliation`)
+      lines.push('')
+      lines.push(`Reconciled against \`${options.partialsDir ? partialsDir : `${options.docsRepo}@${options.docsRef}`}\`.`)
+      lines.push('')
+      if (result.created.length + result.deleted.length === 0 && !result.navUpdated) {
+        lines.push('No changes: stubs and nav already match the partials.')
+      }
+      if (result.created.length > 0) {
+        lines.push(`### New stubs (${result.created.length})`)
+        lines.push('')
+        result.created.forEach(f => lines.push(`- \`${f}\``))
+        lines.push('')
+      }
+      if (result.deleted.length > 0) {
+        lines.push(`### Deleted stubs (${result.deleted.length})`)
+        lines.push('')
+        result.deleted.forEach(f => lines.push(`- \`${f}\``))
+        lines.push('')
+      }
+      if ((result.skippedAliasTargets || []).length > 0) {
+        lines.push('### Skipped: names claimed as page aliases')
+        lines.push('')
+        lines.push('These partials exist upstream, but a page here already claims the name as a `:page-aliases:` target — creating the stub would make the Antora build fatal. Usually this means a rename alias exists while the upstream partial for the old name has not been cleaned up yet:')
+        lines.push('')
+        for (const t of result.skippedAliasTargets) {
+          lines.push(`- \`${t.file}\` (claimed by \`${t.claimedBy}\`)`)
+        }
+        lines.push('')
+      }
+      const straightDeletions = result.deleted.filter(d => !result.renameCandidates.some(rc => rc.deleted === d))
+      if (straightDeletions.length > 0) {
+        lines.push('### Deletions with no rename partner')
+        lines.push('')
+        lines.push('These pages were removed with no successor detected. Their published URLs will 404 — consider adding a redirect or an alias on a related page:')
+        lines.push('')
+        straightDeletions.forEach(f => lines.push(`- \`${f}\``))
+        lines.push('')
+      }
+      if (result.renameCandidates.length > 0) {
+        lines.push('### Possible renames — reviewer decision needed')
+        lines.push('')
+        lines.push('These deleted/created pairs look like renames. If so, add `:page-aliases:` for the old page name to the new stub so published URLs keep working:')
+        lines.push('')
+        for (const rc of result.renameCandidates) {
+          lines.push(`- \`${rc.deleted}\` → \`${rc.created}\`: add \`:page-aliases: reference:rpk/rpk-${plugin}/${rc.deleted}\` to the new stub`)
+        }
+        lines.push('')
+      }
+      if (result.keptNonStub.length > 0) {
+        lines.push('### Kept (not managed stubs)')
+        lines.push('')
+        lines.push('These pages do not match the managed stub shape, so they were not touched:')
+        lines.push('')
+        result.keptNonStub.forEach(f => lines.push(`- \`${f}\``))
+        lines.push('')
+      }
+      const summary = lines.join('\n')
+      if (options.summaryFile) {
+        fs.writeFileSync(options.summaryFile, summary, 'utf8')
+        console.log(`Summary written to: ${options.summaryFile}`)
+      }
+
+      process.exit(0)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
 /**
  * validate rpk-overrides
  *

package/package.json

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

package/tools/property-extractor/property_extractor.py

@@ -753,7 +753,24 @@ def transform_files_with_properties(files_with_properties):
                 continue
 
             if len(property_definition) > 0:
-                all_properties[name] = property_definition
+                # Key the output by the property's registered name (the string
+                # literal passed to the constructor), which can differ from the
+                # C++ member identifier used as the parser key. For example,
+                # the member `default_topic_replication` registers the name
+                # "default_topic_replications".
+                output_key = property_definition.get("name") or name
+                existing = all_properties.get(output_key)
+                if existing is not None and existing.get("defined_in") == property_definition.get("defined_in"):
+                    # Two members of the same config store register the same
+                    # property name. config_store registers properties with
+                    # emplace(), so the first registration wins at runtime.
+                    # Match that behavior and keep the first definition.
+                    logging.warning(
+                        f"Duplicate property name '{output_key}' (member '{name}') in "
+                        f"{property_definition.get('defined_in')}: keeping the first definition."
+                    )
+                    continue
+                all_properties[output_key] = property_definition
 
     return all_properties
 

package/tools/property-extractor/transformers.py

@@ -639,8 +639,9 @@ class BasicInfoTransformer:
     
     NAME RESOLUTION PRIORITY:
     1. Pre-existing property["name"] (from previous processing)
-    2. info["name_in_file"] (C++ variable name from Tree-sitter)  
-    3. First parameter value if it looks like an identifier
+    2. First string-literal parameter if it looks like an identifier
+       (the name argument passed to the property constructor)
+    3. info["name_in_file"] (C++ member name from Tree-sitter) as fallback
     
     DESCRIPTION EXTRACTION LOGIC:
     1. If first parameter is a string and differs from name → use as description
@@ -673,29 +674,44 @@ class BasicInfoTransformer:
             return property
 
         # --- Step 1: find the "real" start of the property definition ---
-        # Skip lambdas, validators, and non-string literals at the start
-        start_idx = 0
+        # Skip lambdas, validators, and non-string literals at the start.
+        # The parser normalizes string_literal values to unquoted strings, so
+        # select by parameter type rather than by surrounding quotes.
+        start_idx = None
         for i, p in enumerate(params):
-            val = str(p.get("value", ""))
-            typ = p.get("type", "")
             if is_validator_param(p):
                 continue
-            if typ in ("lambda_expression", "qualified_identifier", "unresolved_identifier"):
-                continue
-            if not (val.startswith('"') and val.endswith('"')):
+            if p.get("type") != "string_literal":
                 continue
             # First string literal we hit is the name
             start_idx = i
             break
 
         # --- Step 2: extract name and description robustly ---
-        name = property.get("name") or info.get("name_in_file")
-        if not name and len(params) > start_idx:
-            name = params[start_idx].get("value", "").strip('"')
+        # The property's registered name is the first string-literal constructor
+        # argument, NOT the C++ member identifier. They usually match, but not
+        # always: for example, the member `default_topic_replication` registers
+        # the name "default_topic_replications". info["name_in_file"] (the
+        # member identifier) is only a fallback.
+        name = property.get("name")
+        if not name:
+            for p in params:
+                if p.get("type") != "string_literal":
+                    continue
+                candidate = str(p.get("value", "")).strip().strip('"')
+                # The name literal is a single identifier with no whitespace.
+                # If the first string literal looks like a description instead
+                # (for example, the name was passed as a constant), fall back
+                # to the member identifier below.
+                if candidate and not re.search(r"\s", candidate):
+                    name = candidate
+                break  # only the first string literal can be the name
+        if not name:
+            name = info.get("name_in_file")
         property["name"] = name
 
         desc = None
-        if len(params) > start_idx + 1:
+        if start_idx is not None and len(params) > start_idx + 1:
             v0 = params[start_idx].get("value")
             v1 = params[start_idx + 1].get("value")
             if isinstance(v1, str) and len(v1) > 10 and " " in v1:

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

@@ -0,0 +1,291 @@
+'use strict'
+
+/**
+ * Stub reconciler for consumer repos that publish rpk plugin docs through
+ * single-source stubs (adp-docs for rpk ai).
+ *
+ * The docs repo owns the generated partials; consumer repos own one static
+ * stub page per command plus a nav entry. When a plugin release adds or
+ * removes commands, the stubs drift: a new partial has no stub (command
+ * invisible on the consumer site) and a deleted partial leaves a stub with an
+ * unresolved include (broken page). This module reconciles the stub set
+ * against the current partials rather than applying a diff, so it also heals
+ * pre-existing drift and is idempotent.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { spawnSync } = require('child_process')
+
+/**
+ * Read command titles from generated partials. The title line is
+ * authoritative: dashified filenames cannot be reversed unambiguously
+ * (rpk-ai-llm-provider could be `llm provider` or `llm-provider`).
+ * @param {string} partialsDir - Directory of generated .adoc partials
+ * @returns {Array<{file: string, title: string}>} Sorted by command path
+ */
+function readPartialTitles(partialsDir) {
+  const partials = []
+  for (const file of fs.readdirSync(partialsDir)) {
+    if (!file.endsWith('.adoc')) continue
+    const content = fs.readFileSync(path.join(partialsDir, file), 'utf8')
+    const match = content.match(/^= (.+)$/m)
+    if (!match) {
+      console.warn(`Warning: no title line in ${file}; skipping`)
+      continue
+    }
+    partials.push({ file, title: match[1].trim() })
+  }
+  // Hierarchical order: sort by command words so parents precede children
+  partials.sort((a, b) => {
+    const aw = a.title.split(' ')
+    const bw = b.title.split(' ')
+    for (let i = 0; i < Math.max(aw.length, bw.length); i++) {
+      if (aw[i] === bw[i]) continue
+      if (aw[i] === undefined) return -1
+      if (bw[i] === undefined) return 1
+      return aw[i] < bw[i] ? -1 : 1
+    }
+    return 0
+  })
+  return partials
+}
+
+/**
+ * Sparse-clone the docs repo and return the path to a plugin's partials dir.
+ * @param {Object} params
+ * @param {string} params.docsRepo - owner/repo (e.g. redpanda-data/docs)
+ * @param {string} params.docsRef - Branch or tag to read (e.g. main)
+ * @param {string} params.plugin - Plugin command name (e.g. ai)
+ * @returns {string} Local path to the partials directory
+ */
+function fetchPartialsDir({ docsRepo, docsRef, plugin, sourcePath }) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plugin-stubs-'))
+  const repoDir = path.join(tmpDir, 'docs')
+  // ai and cloud content renders as partials; connect renders as pages —
+  // both carry the single-source tag, so either family can be stubbed
+  const sparsePath = sourcePath || `modules/reference/partials/rpk-${plugin}`
+
+  console.log(`Fetching ${sparsePath} from ${docsRepo}@${docsRef}...`)
+  const cloneResult = spawnSync('git', [
+    'clone', '--depth', '1', '--filter=blob:none', '--sparse',
+    '--branch', docsRef,
+    `https://github.com/${docsRepo}.git`, repoDir
+  ], { encoding: 'utf8', timeout: 180000 })
+  if (cloneResult.status !== 0) {
+    throw new Error(`Failed to clone ${docsRepo}@${docsRef}: ${cloneResult.stderr}`)
+  }
+
+  const sparseResult = spawnSync('git', ['sparse-checkout', 'set', sparsePath], {
+    cwd: repoDir, encoding: 'utf8', timeout: 60000
+  })
+  if (sparseResult.status !== 0) {
+    throw new Error(`Failed sparse checkout of ${sparsePath}: ${sparseResult.stderr}`)
+  }
+
+  const partialsDir = path.join(repoDir, sparsePath)
+  if (!fs.existsSync(partialsDir)) {
+    throw new Error(`Partials directory not found in ${docsRepo}@${docsRef}: ${sparsePath}`)
+  }
+  return partialsDir
+}
+
+/**
+ * Infer the include prefix from an existing managed stub, so the reconciler
+ * follows whatever component/module coordinates the consumer repo uses.
+ * @param {string} stubDir - Consumer repo stub directory
+ * @param {string} plugin - Plugin command name
+ * @returns {string|null} e.g. "streaming:reference:partial$rpk-ai/"
+ */
+function inferIncludePrefix(stubDir, plugin) {
+  if (!fs.existsSync(stubDir)) return null
+  for (const file of fs.readdirSync(stubDir)) {
+    if (!file.endsWith('.adoc')) continue
+    const content = fs.readFileSync(path.join(stubDir, file), 'utf8')
+    const match = content.match(new RegExp(`include::([^\\[]*(?:partial|page)\\$[^\\[]*rpk-${plugin}/)`))
+    if (match) return match[1]
+  }
+  return null
+}
+
+/**
+ * Render a stub page.
+ * @param {Object} params
+ * @param {string} params.title - Command path (e.g. "rpk ai auth login")
+ * @param {string} params.file - Partial filename
+ * @param {string} params.includePrefix - Antora resource prefix
+ * @param {Array<string>} params.attributes - Page attribute lines
+ * @returns {string}
+ */
+function renderStub({ title, file, includePrefix, attributes }) {
+  const lines = [`= ${title}`]
+  for (const attr of attributes) lines.push(attr)
+  lines.push('')
+  lines.push(`include::${includePrefix}${file}[tag=single-source]`)
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * Reconcile a consumer repo's stub pages and nav section against the
+ * current set of generated partials.
+ * @param {Object} params
+ * @param {Array<{file: string, title: string}>} params.partials
+ * @param {string} params.stubDir - Consumer stub directory (created if missing)
+ * @param {string} params.navFile - Consumer nav.adoc path
+ * @param {string} params.plugin - Plugin command name (e.g. ai)
+ * @param {string} params.includePrefix - Antora resource prefix for includes
+ * @param {Array<string>} [params.attributes] - Page attributes for new stubs
+ * @param {boolean} [params.dryRun]
+ * @returns {Object} { created, deleted, keptNonStub, navUpdated, renameCandidates }
+ */
+function reconcileStubs({
+  partials,
+  stubDir,
+  navFile,
+  plugin,
+  includePrefix,
+  attributes = [':page-preview: true'],
+  dryRun = false
+}) {
+  const managedStubRe = new RegExp(`include::[^\\[]*(?:partial|page)\\$[^\\[]*rpk-${plugin}/([\\w.-]+\\.adoc)\\[`)
+  const partialByFile = new Map(partials.map(p => [p.file, p]))
+
+  fs.mkdirSync(stubDir, { recursive: true })
+  const existingStubs = fs.readdirSync(stubDir).filter(f => f.endsWith('.adoc'))
+
+  const created = []
+  const deleted = []
+  const keptNonStub = []
+  const skippedAliasTargets = []
+
+  // Page names already claimed as aliases by other pages in this directory.
+  // Creating a page whose resource ID is an alias target makes the Antora
+  // build fatal ("Page alias cannot reference an existing page"), which
+  // happens when a rename alias exists here while the upstream partial for
+  // the old name still lingers. Skip those creations and surface them.
+  const aliasClaims = new Map()
+  for (const file of existingStubs) {
+    const content = fs.readFileSync(path.join(stubDir, file), 'utf8')
+    const aliasLine = content.match(/^:page-aliases:\s*(.+)$/m)
+    if (!aliasLine) continue
+    for (const target of aliasLine[1].split(',')) {
+      const base = target.trim().split('/').pop()
+      if (base) aliasClaims.set(base, file)
+    }
+  }
+
+  // Delete managed stubs whose partial no longer exists. Pages that do not
+  // match the managed-stub shape are never deleted: they may be hand-written.
+  const deletedTitles = new Map()
+  for (const file of existingStubs) {
+    const stubPath = path.join(stubDir, file)
+    const content = fs.readFileSync(stubPath, 'utf8')
+    const match = content.match(managedStubRe)
+    if (!match) {
+      if (!partialByFile.has(file)) keptNonStub.push(file)
+      continue
+    }
+    if (!partialByFile.has(match[1])) {
+      const titleMatch = content.match(/^= (.+)$/m)
+      deletedTitles.set(file, titleMatch ? titleMatch[1].trim() : '')
+      if (!dryRun) fs.unlinkSync(stubPath)
+      deleted.push(file)
+    }
+  }
+
+  // Create stubs for partials that have none
+  const remainingStubs = new Set(
+    fs.existsSync(stubDir) ? fs.readdirSync(stubDir).filter(f => f.endsWith('.adoc')) : []
+  )
+  for (const partial of partials) {
+    if (remainingStubs.has(partial.file)) continue
+    if (aliasClaims.has(partial.file)) {
+      skippedAliasTargets.push({ file: partial.file, claimedBy: aliasClaims.get(partial.file) })
+      continue
+    }
+    if (!dryRun) {
+      fs.writeFileSync(
+        path.join(stubDir, partial.file),
+        renderStub({ ...partial, includePrefix, attributes }),
+        'utf8'
+      )
+    }
+    created.push(partial.file)
+  }
+
+  // Rename candidates: same parent command, same depth, related last words
+  // (llm -> llm-provider). Proposed for the reviewer, who decides whether
+  // the new stub gets a page alias.
+  const renameCandidates = []
+  for (const [dFile, dTitle] of deletedTitles) {
+    if (!dTitle) continue
+    const dWords = dTitle.split(' ')
+    for (const cFile of created) {
+      const cTitle = (partialByFile.get(cFile) || {}).title || ''
+      const cWords = cTitle.split(' ')
+      if (cWords.length !== dWords.length) continue
+      if (cWords.slice(0, -1).join(' ') !== dWords.slice(0, -1).join(' ')) continue
+      const dLast = dWords[dWords.length - 1]
+      const cLast = cWords[cWords.length - 1]
+      if (cLast.startsWith(dLast) || dLast.startsWith(cLast)) {
+        renameCandidates.push({ deleted: dFile, created: cFile })
+      }
+    }
+  }
+
+  // Rebuild the plugin's nav block: keep the labeled parent line, regenerate
+  // child entries from titles at star depth = parent depth + (words - 2)
+  let navUpdated = false
+  if (navFile && fs.existsSync(navFile)) {
+    const navLines = fs.readFileSync(navFile, 'utf8').split('\n')
+    const parentRe = new RegExp(`^(\\*+) xref:[^\\[]*rpk-${plugin}/rpk-${plugin}\\.adoc\\[`)
+    const parentIdx = navLines.findIndex(l => parentRe.test(l))
+    if (parentIdx === -1) {
+      console.warn(`Warning: no rpk-${plugin} parent entry found in ${navFile}; nav not updated`)
+    } else {
+      const parentStars = navLines[parentIdx].match(parentRe)[1].length
+      const navPathPrefix = navLines[parentIdx].match(/xref:([^\[]*rpk-\w+\/)/)[1]
+
+      // The block ends at the first line that is not a deeper entry
+      let end = parentIdx + 1
+      while (end < navLines.length) {
+        const starMatch = navLines[end].match(/^(\*+) /)
+        if (!starMatch || starMatch[1].length <= parentStars) break
+        end++
+      }
+
+      const skippedFiles = new Set(skippedAliasTargets.map(t => t.file))
+      const entries = []
+      for (const partial of partials) {
+        if (skippedFiles.has(partial.file)) continue
+        const words = partial.title.split(' ').length
+        if (words <= 2) continue // the parent line represents the root command
+        const stars = '*'.repeat(parentStars + (words - 2))
+        entries.push(`${stars} xref:${navPathPrefix}${partial.file}[]`)
+      }
+
+      const rebuilt = [
+        ...navLines.slice(0, parentIdx + 1),
+        ...entries,
+        ...navLines.slice(end)
+      ].join('\n')
+
+      if (rebuilt !== navLines.join('\n')) {
+        if (!dryRun) fs.writeFileSync(navFile, rebuilt, 'utf8')
+        navUpdated = true
+      }
+    }
+  }
+
+  return { created, deleted, keptNonStub, navUpdated, renameCandidates, skippedAliasTargets }
+}
+
+module.exports = {
+  readPartialTitles,
+  fetchPartialsDir,
+  inferIncludePrefix,
+  renderStub,
+  reconcileStubs
+}