@redpanda-data/docs-extensions-and-macros 4.13.2 → 4.13.3

package/bin/doc-tools-mcp.js

@@ -362,7 +362,7 @@ const tools = [
         },
         surface: {
           type: 'string',
-          description: 'Which API surface(s) to bundle (optional, defaults to "both")',
+          description: 'Which API surfaces to bundle (optional, defaults to "both")',
           enum: ['admin', 'connect', 'both']
         },
         out_admin: {

package/bin/doc-tools.js

@@ -1630,7 +1630,7 @@ automation
   .option('-t, --tag <tag>', 'Git tag for released content')
   .option('-b, --branch <branch>', 'Branch name for in-progress content')
   .option('--repo <url>', 'Repository URL', 'https://github.com/redpanda-data/redpanda.git')
-  .addOption(new Option('-s, --surface <surface>', 'Which API surface(s) to bundle').choices(['admin', 'connect', 'both']).makeOptionMandatory())
+  .addOption(new Option('-s, --surface <surface>', 'Which API surfaces to bundle').choices(['admin', 'connect', 'both']).makeOptionMandatory())
   .option('--out-admin <path>', 'Output path for admin API', 'admin/redpanda-admin-api.yaml')
   .option('--out-connect <path>', 'Output path for connect API', 'connect/redpanda-connect-api.yaml')
   .option('--admin-major <string>', 'Admin API major version', 'v2.0.0')

package/bin/mcp-tools/generated-docs-review.js

@@ -306,10 +306,10 @@ function generateReviewReport(results, outputPath) {
   // Next steps
   report += `== Next Steps\n\n`;
   if (errorIssues.length > 0) {
-    report += `. *Fix errors first* - Address the ${errorIssues.length} error(s) above\n`;
+    report += `. *Fix errors first* - Address the ${errorIssues.length} errors above\n`;
   }
   if (warningIssues.length > 0) {
-    report += `${errorIssues.length > 0 ? '. ' : '. '}*Review warnings* - Prioritize the ${warningIssues.length} warning(s)\n`;
+    report += `${errorIssues.length > 0 ? '. ' : '. '}*Review warnings* - Prioritize the ${warningIssues.length} warnings\n`;
   }
   const step = errorIssues.length > 0 && warningIssues.length > 0 ? 3 : errorIssues.length > 0 || warningIssues.length > 0 ? 2 : 1;
   report += `${step > 1 ? '. ' : '. '}*Regenerate documentation* - After making changes, regenerate the docs\n`;

package/bin/mcp-tools/mcp-validation.js

@@ -250,7 +250,7 @@ function formatValidationResults(results, config) {
     lines.push('✓ Validation passed');
   } else {
     lines.push('✗ Validation failed');
-    lines.push(`  ${results.errors.length} error(s) must be fixed`);
+    lines.push(`  ${results.errors.length} errors must be fixed`);
   }
 
   return lines.join('\n');

package/bin/mcp-tools/openapi.js

@@ -16,7 +16,7 @@ const { getAntoraStructure } = require('./antora');
  * @param {string} [args.tag] - Git tag for released content (for example, "v24.3.2" or "24.3.2")
  * @param {string} [args.branch] - Branch name for in-progress content (for example, "dev", "main")
  * @param {string} [args.repo] - Repository URL
- * @param {string} [args.surface] - Which API surface(s) to bundle: 'admin', 'connect', or 'both'
+ * @param {string} [args.surface] - Which API surfaces to bundle: 'admin', 'connect', or 'both'
  * @param {string} [args.out_admin] - Output path for admin API
  * @param {string} [args.out_connect] - Output path for connect API
  * @param {string} [args.admin_major] - Admin API major version
@@ -155,7 +155,7 @@ function generateBundleOpenApi(args) {
       surface,
       files_generated: filesGenerated,
       output: output.trim(),
-      summary: `Bundled OpenAPI documentation for ${surface} API(s) at ${refType} ${version}`
+      summary: `Bundled OpenAPI documentation for ${surface} APIs at ${refType} ${version}`
     };
   } catch (err) {
     return {

package/extensions/generate-rp-connect-categories.js

@@ -73,7 +73,6 @@ module.exports.register = function ({ config }) {
         const status = attrs.status || extractAttribute(file, 'status')
         const driverSupport = attrs['driver-support'] || extractAttribute(file, 'driver-support')
         const cacheSupport = attrs['cache-support'] || extractAttribute(file, 'cache-support')
-        // FIXED: Use correct attribute name (page-commercial-names, not commercial-names)
         const commercialNames = attrs['page-commercial-names'] || extractAttribute(file, 'page-commercial-names')
 
         const pubUrl = file.pub.url

package/package.json

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

package/tools/bundle-openapi.js

@@ -551,7 +551,7 @@ function postProcessBundle(filePath, options, quiet = false) {
 }
 
 /**
- * Bundle OpenAPI fragments for the specified API surface(s) from a repository tag and write the resulting bundled YAML files to disk.
+ * Bundle OpenAPI fragments for the specified API surfaces from a repository tag and write the resulting bundled YAML files to disk.
  *
  * @param {Object} options - Configuration options.
  * @param {string} options.tag - Git tag to checkout (for example, 'v25.1.1').

package/tools/redpanda-connect/README.adoc

@@ -665,13 +665,13 @@ Connectors can have human-friendly commercial names that appear in catalogs and
 ----
 = kafka_franz
 :type: input
-:commercial-names: Franz-go, Apache Kafka
+:page-commercial-names: Franz-go, Apache Kafka
 :categories: ["Services"]
 ----
 
 The `generate-rp-connect-categories` extension reads these commercial names and uses the first one as the primary display name. If multiple names are provided (comma-separated), only the first is used for display.
 
-*Default behavior:* If no `:commercial-names:` attribute is found, the connector key name is used (e.g., `kafka_franz`).
+*Default behavior:* If no `:page-commercial-names:` attribute is found, the connector key name is used (such as `kafka_franz`).
 
 *Adding commercial names to new connectors:*
 
@@ -681,12 +681,12 @@ When generating documentation for new connectors with `--draft-missing`, writers
 ----
 ### ✍️ Writer Action Required
 
-For each new connector, please add the `:commercial-names:` attribute to the frontmatter:
+For each new connector, please add the `:page-commercial-names:` attribute to the frontmatter:
 
 ```asciidoc
 = Connector Name
 :type: input
-:commercial-names: Commercial Name, Alternative Name
+:page-commercial-names: Commercial Name, Alternative Name
 ```
 
 _This helps improve discoverability and ensures proper categorization._

package/tools/redpanda-connect/connector-binary-analyzer.js

@@ -503,7 +503,7 @@ async function analyzeAllBinaries(ossVersion, cloudVersion = null, dataDir = nul
       // These are connectors that require cgo-enabled builds
       cgoOnly = findCgoOnlyConnectors(ossIndex, cgoIndex);
 
-      console.log(`Done: Cgo analysis complete: ${cgoOnly.length} cgo-only connector(s) found`);
+      console.log(`Done: Cgo analysis complete: ${cgoOnly.length} cgo-only connectors found`);
       if (cgoOnly.length > 0) {
         console.log('   cgo-only connectors:');
         cgoOnly.forEach(c => console.log(`   • ${c.type}/${c.name} (${c.status})`));

package/tools/redpanda-connect/pr-summary-formatter.js

@@ -30,7 +30,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   // High-level stats
   const stats = diffData.summary;
-  const hasChanges = Object.values(stats).some(v => v > 0);
+  const hasChanges = Object.values(stats).some(v => v > 0) || (draftedConnectors && draftedConnectors.length > 0);
 
   if (!hasChanges) {
     lines.push('✅ **No changes detected** - Documentation is up to date');
@@ -91,16 +91,78 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   if (stats.newComponents > 0) {
     lines.push('### ✍️ Writer Action Required');
     lines.push('');
-    lines.push('For each new connector, please add the `:commercial-names:` attribute to the frontmatter:');
+    lines.push('For each new connector, add the `:page-commercial-names:` attribute to the frontmatter:');
     lines.push('');
     lines.push('```asciidoc');
     lines.push('= Connector Name');
     lines.push(':type: input');
-    lines.push(':commercial-names: Commercial Name, Alternative Name');
+    lines.push(':page-commercial-names: Commercial Name, Alternative Name');
     lines.push('```');
     lines.push('');
     lines.push('_This helps improve discoverability and ensures proper categorization._');
     lines.push('');
+
+    // Check if any new connectors are cloud-supported
+    if (binaryAnalysis && binaryAnalysis.comparison) {
+      const newConnectorKeys = diffData.details.newComponents.map(c => ({
+        key: `${c.type}:${c.name}`,
+        type: c.type,
+        name: c.name
+      }));
+
+      const cloudSupported = newConnectorKeys.filter(item => {
+        // Check both inCloud (OSS+Cloud) and cloudOnly (Cloud-only)
+        const inCloud = binaryAnalysis.comparison.inCloud.some(c => `${c.type}:${c.name}` === item.key);
+        const cloudOnly = binaryAnalysis.comparison.cloudOnly &&
+          binaryAnalysis.comparison.cloudOnly.some(c => `${c.type}:${c.name}` === item.key);
+        return inCloud || cloudOnly;
+      });
+
+      if (cloudSupported.length > 0) {
+        lines.push('### ☁️ Cloud Docs Update Required');
+        lines.push('');
+        lines.push(`**${cloudSupported.length}** new connector${cloudSupported.length !== 1 ? 's are' : ' is'} available in Redpanda Cloud.`);
+        lines.push('');
+        lines.push('**Action:** Submit a separate PR to https://github.com/redpanda-data/cloud-docs to add the connector pages using include syntax:');
+        lines.push('');
+
+        // Check if any are cloud-only (need partial syntax)
+        const cloudOnly = cloudSupported.filter(item =>
+          binaryAnalysis.comparison.cloudOnly &&
+          binaryAnalysis.comparison.cloudOnly.some(c => `${c.type}:${c.name}` === item.key)
+        );
+        const regularCloud = cloudSupported.filter(item =>
+          !binaryAnalysis.comparison.cloudOnly ||
+          !binaryAnalysis.comparison.cloudOnly.some(c => `${c.type}:${c.name}` === item.key)
+        );
+
+        if (regularCloud.length > 0) {
+          lines.push('**For connectors in pages:**');
+          lines.push('```asciidoc');
+          lines.push('= Connector Name');
+          lines.push('');
+          lines.push('include::redpanda-connect:components:page$type/connector-name.adoc[tag=single-source]');
+          lines.push('```');
+          lines.push('');
+        }
+
+        if (cloudOnly.length > 0) {
+          lines.push('**For cloud-only connectors (in partials):**');
+          lines.push('```asciidoc');
+          lines.push('= Connector Name');
+          lines.push('');
+          lines.push('include::redpanda-connect:components:partial$components/cloud-only/type/connector-name.adoc[tag=single-source]');
+          lines.push('```');
+          lines.push('');
+        }
+
+        // Add instruction to update cloud whats-new
+        lines.push('**Also update the cloud whats-new file:**');
+        lines.push('');
+        lines.push('Add entries for the new cloud-supported connectors to the Redpanda Cloud whats-new file in the cloud-docs repository.');
+        lines.push('');
+      }
+    }
   }
 
   // Breaking Changes Section

package/tools/redpanda-connect/report-delta.js

@@ -250,6 +250,7 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
     result.binaryAnalysis.details = {
       cloudSupported: ba.comparison?.inCloud?.map(c => ({ type: c.type, name: c.name, status: c.status })) || [],
       selfHostedOnly: ba.comparison?.notInCloud?.map(c => ({ type: c.type, name: c.name, status: c.status })) || [],
+      cloudOnly: ba.comparison?.cloudOnly?.map(c => ({ type: c.type, name: c.name, status: c.status })) || [],
       cgoOnly: ba.cgoOnly?.map(c => ({ type: c.type, name: c.name, status: c.status })) || []
     };
   }

package/tools/redpanda-connect/rpcn-connector-docs-handler.js

@@ -148,13 +148,20 @@ function updateWhatsNew ({ dataDir, oldVersion, newVersion, binaryAnalysis }) {
     const regularComponents = []
 
     if (diff.details.newComponents && diff.details.newComponents.length) {
-      for (const comp of diff.details.newComponents) {
+      // Filter out cloud-only connectors - they don't go in whats-new.adoc
+      const nonCloudOnlyComponents = diff.details.newComponents.filter(comp => {
+        const isCloudOnly = diff.binaryAnalysis?.details?.cloudOnly?.some(cloudComp => {
+          return cloudComp.name === comp.name && cloudComp.type === comp.type
+        })
+        return !isCloudOnly
+      })
+
+      for (const comp of nonCloudOnlyComponents) {
         if (comp.type === 'bloblang-functions' || comp.type === 'bloblang-methods') {
           bloblangComponents.push(comp)
         } else {
-          const isCgoOnly = binaryAnalysis?.cgoOnly?.some(cgo => {
-            const typeSingular = cgo.type.replace(/s$/, '')
-            return cgo.name === comp.name && typeSingular === comp.type
+          const isCgoOnly = diff.binaryAnalysis?.details?.cgoOnly?.some(cgo => {
+            return cgo.name === comp.name && cgo.type === comp.type
           })
 
           regularComponents.push({
@@ -654,6 +661,27 @@ async function handleRpcnConnectorDocs (options) {
 
   let newIndex = JSON.parse(fs.readFileSync(dataFile, 'utf8'))
 
+  // Save a clean copy of OSS data for binary analysis (before augmentation)
+  // This ensures the binary analyzer compares actual binaries, not augmented data
+  const cleanOssDataPath = path.join(dataDir, `._connect-${newVersion}-clean.json`)
+
+  // Strip augmentation fields to create clean data for comparison
+  const cleanData = JSON.parse(JSON.stringify(newIndex))
+  const connectorTypes = ['inputs', 'outputs', 'processors', 'caches', 'rate_limits', 'buffers', 'metrics', 'scanners', 'tracers']
+
+  for (const type of connectorTypes) {
+    if (Array.isArray(cleanData[type])) {
+      cleanData[type] = cleanData[type].filter(c => !c.cloudOnly) // Remove cloud-only connectors added by augmentation
+      cleanData[type].forEach(c => {
+        delete c.cloudSupported
+        delete c.requiresCgo
+        delete c.cloudOnly
+      })
+    }
+  }
+
+  fs.writeFileSync(cleanOssDataPath, JSON.stringify(cleanData, null, 2), 'utf8')
+
   const versionsMatch = oldVersion && newVersion && oldVersion === newVersion
   if (versionsMatch) {
     console.log(`\n✓ Already at version ${newVersion}`)
@@ -740,6 +768,19 @@ async function handleRpcnConnectorDocs (options) {
     console.log('\nAnalyzing connector binaries...')
     const { analyzeAllBinaries } = require('./connector-binary-analyzer.js')
 
+    // Always use clean OSS data for comparison
+    // Temporarily rename the file so the analyzer finds it
+    const expectedPath = path.join(dataDir, `connect-${newVersion}.json`)
+    let tempRenamed = false
+
+    if (fs.existsSync(cleanOssDataPath)) {
+      if (fs.existsSync(expectedPath)) {
+        fs.renameSync(expectedPath, path.join(dataDir, `._connect-${newVersion}-augmented.json.tmp`))
+        tempRenamed = true
+      }
+      fs.copyFileSync(cleanOssDataPath, expectedPath)
+    }
+
     const analysisOptions = {
       skipCloud: false,
       skipCgo: false,
@@ -753,6 +794,13 @@ async function handleRpcnConnectorDocs (options) {
       analysisOptions
     )
 
+    // Restore the augmented file
+    if (tempRenamed) {
+      const expectedPath = path.join(dataDir, `connect-${newVersion}.json`)
+      fs.unlinkSync(expectedPath)
+      fs.renameSync(path.join(dataDir, `._connect-${newVersion}-augmented.json.tmp`), expectedPath)
+    }
+
     console.log('Done: Binary analysis complete:')
     console.log(`   • OSS version: ${binaryAnalysis.ossVersion}`)
 
@@ -848,10 +896,10 @@ async function handleRpcnConnectorDocs (options) {
       fs.writeFileSync(dataFile, JSON.stringify(connectorData, null, 2), 'utf8')
       console.log(`Done: Augmented ${augmentedCount} connectors with cloud/cgo fields`)
       if (addedCgoCount > 0) {
-        console.log(`   • Added ${addedCgoCount} cgo-only connector(s) to data file`)
+        console.log(`   • Added ${addedCgoCount} cgo-only connectors to data file`)
       }
       if (addedCloudOnlyCount > 0) {
-        console.log(`   • Added ${addedCloudOnlyCount} cloud-only connector(s) to data file`)
+        console.log(`   • Added ${addedCloudOnlyCount} cloud-only connectors to data file`)
       }
 
       // Keep only 2 most recent versions
@@ -890,8 +938,42 @@ async function handleRpcnConnectorDocs (options) {
       }
     )
 
+    // Filter out components that already have documentation
+    const docRoots = {
+      pages: path.resolve(process.cwd(), 'modules/components/pages'),
+      partials: path.resolve(process.cwd(), 'modules/components/partials/components'),
+      cloudOnly: path.resolve(process.cwd(), 'modules/components/partials/components/cloud-only')
+    }
+
+    if (diffJson.details && diffJson.details.newComponents) {
+      const originalCount = diffJson.details.newComponents.length
+      diffJson.details.newComponents = diffJson.details.newComponents.filter(comp => {
+        const typePlural = comp.type.endsWith('s') ? comp.type : `${comp.type}s`
+        const relPath = path.join(typePlural, `${comp.name}.adoc`)
+        const docsExist = Object.values(docRoots).some(root =>
+          fs.existsSync(path.join(root, relPath))
+        )
+        return !docsExist
+      })
+      const filteredCount = originalCount - diffJson.details.newComponents.length
+      if (filteredCount > 0) {
+        console.log(`   ℹ️  Filtered out ${filteredCount} components that already have documentation`)
+      }
+      // Update summary count
+      if (diffJson.summary) {
+        diffJson.summary.newComponents = diffJson.details.newComponents.length
+      }
+    }
+
     // Add new cgo-only components
     if (binaryAnalysis && binaryAnalysis.cgoOnly && binaryAnalysis.cgoOnly.length > 0) {
+      // Define roots for checking if docs already exist
+      const docRoots = {
+        pages: path.resolve(process.cwd(), 'modules/components/pages'),
+        partials: path.resolve(process.cwd(), 'modules/components/partials/components'),
+        cloudOnly: path.resolve(process.cwd(), 'modules/components/partials/components/cloud-only')
+      }
+
       let newCgoComponents
 
       if (oldBinaryAnalysis) {
@@ -899,20 +981,36 @@ async function handleRpcnConnectorDocs (options) {
         newCgoComponents = binaryAnalysis.cgoOnly.filter(cgoComp => {
           const wasInOldOss = oldIndex[cgoComp.type]?.some(c => c.name === cgoComp.name)
           const wasInOldCgo = oldCgoSet.has(`${cgoComp.type}:${cgoComp.name}`)
-          return !wasInOldOss && !wasInOldCgo
+
+          // Check if docs already exist
+          const typePlural = cgoComp.type.endsWith('s') ? cgoComp.type : `${cgoComp.type}s`
+          const relPath = path.join(typePlural, `${cgoComp.name}.adoc`)
+          const docsExist = Object.values(docRoots).some(root =>
+            fs.existsSync(path.join(root, relPath))
+          )
+
+          return !wasInOldOss && !wasInOldCgo && !docsExist
         })
       } else {
         newCgoComponents = binaryAnalysis.cgoOnly.filter(cgoComp => {
           const wasInOldOss = oldIndex[cgoComp.type]?.some(c => c.name === cgoComp.name)
-          return !wasInOldOss
+
+          // Check if docs already exist
+          const typePlural = cgoComp.type.endsWith('s') ? cgoComp.type : `${cgoComp.type}s`
+          const relPath = path.join(typePlural, `${cgoComp.name}.adoc`)
+          const docsExist = Object.values(docRoots).some(root =>
+            fs.existsSync(path.join(root, relPath))
+          )
+
+          return !wasInOldOss && !docsExist
         })
         if (newCgoComponents.length > 0) {
-          console.log(`   ℹ️  No old binary analysis found - treating ${newCgoComponents.length} cgo component(s) not in old OSS data as new`)
+          console.log(`   ℹ️  No old binary analysis found - treating ${newCgoComponents.length} cgo components not in old OSS data as new`)
         }
       }
 
       if (newCgoComponents && newCgoComponents.length > 0) {
-        console.log(`   • Found ${newCgoComponents.length} new cgo-only component(s)`)
+        console.log(`   • Found ${newCgoComponents.length} new cgo-only components`)
         newCgoComponents.forEach(cgoComp => {
           const typeSingular = cgoComp.type.replace(/s$/, '')
           diffJson.details.newComponents.push({
@@ -940,7 +1038,7 @@ async function handleRpcnConnectorDocs (options) {
         .filter(f => f.startsWith('connect-diff-') && f.endsWith('.json') && f !== path.basename(diffPath))
 
       if (oldDiffFiles.length > 0) {
-        console.log(`🧹 Cleaning up ${oldDiffFiles.length} old diff file(s)...`)
+        console.log(`🧹 Cleaning up ${oldDiffFiles.length} old diff files...`)
         oldDiffFiles.forEach(f => {
           const oldDiffPath = path.join(dataDir, f)
           fs.unlinkSync(oldDiffPath)
@@ -1011,7 +1109,8 @@ async function handleRpcnConnectorDocs (options) {
 
       const roots = {
         pages: path.resolve(process.cwd(), 'modules/components/pages'),
-        partials: path.resolve(process.cwd(), 'modules/components/partials/components')
+        partials: path.resolve(process.cwd(), 'modules/components/partials/components'),
+        cloudOnly: path.resolve(process.cwd(), 'modules/components/partials/components/cloud-only')
       }
 
       const allMissing = validConnectors.filter(({ name, type }) => {

package/tools/redpanda-connect/update-nav.js

@@ -190,7 +190,18 @@ function updateNavFromDrafts(draftFiles, navPath = null) {
 
   console.log(`📝 Updating navigation: ${navPath}`);
 
-  const connectors = draftFiles.map(draft => ({
+  // Filter out cloud-only connectors (they go in partials, not nav)
+  const nonCloudOnlyFiles = draftFiles.filter(draft => !draft.cloudOnly);
+  const cloudOnlyFiles = draftFiles.filter(draft => draft.cloudOnly);
+
+  if (cloudOnlyFiles.length > 0) {
+    console.log(`   ℹ️  Skipping ${cloudOnlyFiles.length} cloud-only connectors (partials don't need nav entries):`);
+    cloudOnlyFiles.forEach(draft => {
+      console.log(`      • ${draft.type}/${draft.name}`);
+    });
+  }
+
+  const connectors = nonCloudOnlyFiles.map(draft => ({
     type: draft.type,
     name: draft.name
   }));