@redpanda-data/docs-extensions-and-macros 5.51.0 → 5.51.2

package/mcp/CLI_INTERFACE.adoc

@@ -379,7 +379,7 @@ Test categories:
 If a breaking change to the CLI is necessary:
 
 . Update the CLI with the breaking change
-. Increment the major version in package.json
+. Mark the pull request as breaking with `!` after its type, for example `feat(cli)!: rename --tag to --ref`, so release-please cuts a major release
 . Update the MCP server to handle both old and new interfaces (if possible)
 . Update the CLI contract tests to verify the new interface
 . Update this document with the new contract

package/mcp/DEVELOPMENT.adoc

@@ -487,17 +487,13 @@ All CLI commands have:
 === Before releasing
 
 . Run all tests: `npm run test:mcp`
-. Update version in `package.json`
 . Update link:USER_GUIDE.adoc[USER_GUIDE.adoc] with any changes
 . Test manually with Claude Code
 . Check that setup command works: `npx doc-tools setup-mcp`
 
 === Publishing
 
-. Commit all changes
-. Tag the release: `git tag -a v1.2.3 -m "Release 1.2.3"`
-. Push with tags: `git push --tags`
-. Publish to npm: `npm publish`
+Do not change the version, tag, or run `npm publish` by hand. Give your pull request a conventional-commit title (`feat(mcp): ...` or `fix(mcp): ...`). After it merges, release-please adds it to the open release pull request, and merging that pull request tags and publishes the release. See the Releases section of link:../CONTRIBUTING.adoc[CONTRIBUTING.adoc].
 
 === After releasing
 

package/package.json

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

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

@@ -2848,14 +2848,20 @@ async function generateRpkDocs(options = {}) {
     // Build subcommands with correct xref paths
     // Filter out excluded and asPartial subcommands — excluded have no file,
     // asPartial ones live in the partials directory with no linkable xref.
+    // The exception is a parent that is itself asPartial: its partial is
+    // included by a stub in the component that publishes the whole subtree
+    // (rpk sql in cloud-docs, rpk ai in adp-docs), so relative xrefs to its
+    // children resolve there, the same way rpk cloud partials link.
     // rpk cloud and rpk security secret rows stay in the table: their pages
     // are routed to the cloud partials directory and published by
     // cloud-docs, so the xref below links across to the cloud component
     // instead of dropping the row (which hid the subcommand entirely).
+    const parentIsPartial = shouldUsePartialDir(resolvedOverrides, commandPath)
     const subcommands = (command.commands || [])
       .filter(sub => {
         const subPath = `${commandPath} ${sub.name}`
-        return !shouldExcludeCommand(resolvedOverrides, subPath) && !shouldUsePartialDir(resolvedOverrides, subPath)
+        return !shouldExcludeCommand(resolvedOverrides, subPath) &&
+          (parentIsPartial || !shouldUsePartialDir(resolvedOverrides, subPath))
       })
       .map(sub => {
         const subPath = `${commandPath} ${sub.name}`

package/tools/rpk-docs/helpers/index.js

@@ -315,7 +315,7 @@ function sectionTitle(name) {
   // Acronyms that should remain ALL CAPS
   const acronyms = new Set([
     'id', 'ip', 'api', 'url', 'uri', 'cpu', 'gpu', 'ram', 'io',
-    'tls', 'ssl', 'mtls', 'sasl', 'oauth', 'oidc', 'jwt',
+    'tls', 'ssl', 'mtls', 'sasl', 'sso', 'oauth', 'oidc', 'jwt',
     'json', 'yaml', 'xml', 'csv', 'http', 'https', 'grpc', 'rpc',
     'aws', 'gcp', 'azure', 's3', 'eos'
   ])

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

@@ -1137,15 +1137,21 @@ const WHATS_NEW_EXCLUDED_SUBTREES = ['rpk ai']
 
 /**
  * Return a copy of diffData without entries under the excluded subtrees.
+ * Commands marked asPartial in the overrides are dropped too: they render
+ * only as partials single-sourced into another component (for example,
+ * rpk sql for Redpanda SQL in Cloud), so they are not Self-Managed changes.
  * Only the published What's-new block filters; diff reports and PR
  * summaries keep the full picture.
  * @param {Object} diffData - Diff from generateRpkDiff
  * @param {string[]} [excluded] - Command-path prefixes to drop
+ * @param {Object} [overridesData] - rpk overrides; asPartial subtrees are dropped
  * @returns {Object} Filtered copy
  */
-function filterDiffForWhatsNew(diffData, excluded = WHATS_NEW_EXCLUDED_SUBTREES) {
+function filterDiffForWhatsNew(diffData, excluded = WHATS_NEW_EXCLUDED_SUBTREES, overridesData = null) {
+  const resolved = overridesData ? resolveReferences(overridesData, overridesData) : null
   const outside = (cmdPath) => !excluded.some(prefix =>
-    cmdPath === prefix || (typeof cmdPath === 'string' && cmdPath.startsWith(prefix + ' ')))
+    cmdPath === prefix || (typeof cmdPath === 'string' && cmdPath.startsWith(prefix + ' '))) &&
+    !(resolved && typeof cmdPath === 'string' && shouldUsePartialDir(resolved, cmdPath))
   const details = diffData.details || {}
   const filteredDetails = { ...details }
   for (const key of ['newCommands', 'newlyDeprecatedCommands', 'removedCommands', 'descriptionChanges']) {
@@ -1167,7 +1173,28 @@ function updateWhatsNewFile(diffData, whatsNewPath, version, options = {}) {
     ...options
   })
 
+  const startMarker = `// AUTOGEN-RPK-CHANGES ${version} START`
+  const endMarker = `// AUTOGEN-RPK-CHANGES ${version} END`
+  const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
   if (!whatsNewContent) {
+    // A re-run for a version that now has nothing to publish (for example,
+    // every change was filtered out as asPartial) must remove that version's
+    // earlier block, or the page keeps publishing what the filter excluded.
+    if (fs.existsSync(whatsNewPath)) {
+      const existing = fs.readFileSync(whatsNewPath, 'utf8')
+      if (existing.includes(startMarker)) {
+        const blockRe = new RegExp(`\\n*${escapeRe(startMarker)}[\\s\\S]*?${escapeRe(endMarker)}\\n*`)
+        let updated = existing.replace(blockRe, '\n\n')
+        // Drop the section heading too if the block was all it held, so no
+        // empty heading is left on the page.
+        const emptySectionRe = new RegExp(`^${escapeRe(sectionHeading)}[^\\n]*\\n\\s*(?=^== |(?![\\s\\S]))`, 'm')
+        updated = updated.replace(emptySectionRe, '')
+        fs.writeFileSync(whatsNewPath, updated.replace(/\s*$/, '\n'), 'utf8')
+        console.log(`Removed ${version} block from what's-new file (no changes left to publish): ${whatsNewPath}`)
+        return
+      }
+    }
     console.log('No Redpanda CLI changes to add to what\'s new')
     return
   }
@@ -1187,11 +1214,8 @@ function updateWhatsNewFile(diffData, whatsNewPath, version, options = {}) {
   // Redpanda CLI section instead of being dropped. Writers can edit or
   // remove blocks freely; the automation only ever touches content between
   // its own markers for the same version label.
-  const startMarker = `// AUTOGEN-RPK-CHANGES ${version} START`
-  const endMarker = `// AUTOGEN-RPK-CHANGES ${version} END`
   const sectionBody = whatsNewContent.replace(/^== [^\n]*\n+/, '')
   const block = `${startMarker}\n${sectionBody.trimEnd()}\n${endMarker}`
-  const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
   if (existingContent.includes(startMarker)) {
     // Replace this version's existing block (idempotent re-runs)
@@ -2145,7 +2169,7 @@ async function handleRpkDocsGeneration(options = {}) {
 
           // Update what's-new file if requested
           if (whatsNewPath) {
-            updateWhatsNewFile(filterDiffForWhatsNew(diffData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
+            updateWhatsNewFile(filterDiffForWhatsNew(diffData, WHATS_NEW_EXCLUDED_SUBTREES, overridesData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
           }
         } else {
           console.warn(`Warning: Could not load previous version ${diffVersion} for diff`)
@@ -2467,7 +2491,7 @@ async function handleRpkDocsGeneration(options = {}) {
 
         // Update what's-new file if requested
         if (whatsNewPath) {
-          updateWhatsNewFile(filterDiffForWhatsNew(diffData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
+          updateWhatsNewFile(filterDiffForWhatsNew(diffData, WHATS_NEW_EXCLUDED_SUBTREES, overridesData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
         }
       } else {
         console.warn(`Warning: Could not load previous version ${diffVersion} for diff`)