@redpanda-data/docs-extensions-and-macros 4.6.1 → 4.6.3

package/bin/doc-tools.js

@@ -546,22 +546,27 @@ automation
     }
 
     if (options.draftMissing) {
-      console.log('⏳ Drafting missing connectors...');
+      console.log('⏳ Drafting missing connectors…');
       try {
         const connectorList = await parseCSVConnectors(options.csv, console);
-        const validConnectors = connectorList.filter(row => row.name && row.type);
+        const validConnectors = connectorList.filter(r => r.name && r.type);
 
-        const pagesRoot = path.resolve(process.cwd(), 'modules/components/pages');
+        const roots = {
+          pages:   path.resolve(process.cwd(), 'modules/components/pages'),
+          partials:path.resolve(process.cwd(), 'modules/components/partials/components'),
+        };
+
+        // find any connector that has NO .adoc under pages/TYPEs or partials/TYPEs
         const allMissing = validConnectors.filter(({ name, type }) => {
-          if (!name || !type) {
-            console.warn(`⚠️  Skipping invalid connector entry:`, { name, type });
-            return false;
-          }
-          const expected = path.join(pagesRoot, `${type}s`, `${name}.adoc`);
-          return !fs.existsSync(expected);
+          const relPath = path.join(`${type}s`, `${name}.adoc`);
+          const existsInAny = Object.values(roots).some(root =>
+            fs.existsSync(path.join(root, relPath))
+          );
+          return !existsInAny;
         });
 
-        const missingConnectors = allMissing.filter(({ name }) => !name.includes('sql_driver'));
+        // still skip sql_driver
+        const missingConnectors = allMissing.filter(c => !c.name.includes('sql_driver'));
 
         if (missingConnectors.length === 0) {
           console.log('✅ All connectors (excluding sql_drivers) already have docs—nothing to draft.');
@@ -572,17 +577,20 @@ automation
           });
           console.log('');
 
+          // build your filtered JSON as before…
           const rawData = fs.readFileSync(dataFile, 'utf8');
           const dataObj = JSON.parse(rawData);
-
           const filteredDataObj = {};
+
           for (const [key, arr] of Object.entries(dataObj)) {
             if (!Array.isArray(arr)) {
               filteredDataObj[key] = arr;
               continue;
             }
             filteredDataObj[key] = arr.filter(component =>
-              missingConnectors.some(m => m.name === component.name && `${m.type}s` === key)
+              missingConnectors.some(
+                m => m.name === component.name && `${m.type}s` === key
+              )
             );
           }
 
@@ -590,12 +598,12 @@ automation
           fs.writeFileSync(tempDataPath, JSON.stringify(filteredDataObj, null, 2), 'utf8');
 
           const draftResult = await generateRpcnConnectorDocs({
-            data: tempDataPath,
-            overrides: options.overrides,
-            template: options.templateMain,
-            templateFields: options.templateFields,
-            templateExamples: options.templateExamples,
-            templateIntro: options.templateIntro,
+            data:            tempDataPath,
+            overrides:       options.overrides,
+            template:        options.templateMain,
+            templateFields:  options.templateFields,
+            templateExamples:options.templateExamples,
+            templateIntro:   options.templateIntro,
             writeFullDrafts: true
           });
 

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

@@ -115,40 +115,58 @@ module.exports.register = function ({ config }) {
       let redpandaConnectUrl = '';
       let redpandaCloudUrl = '';
 
+      function isConnectorDocPath (filePath, type) {
+        const dirsToCheck = [
+          `pages/${type}s/`,
+          `partials/components/${type}s/`
+        ];
+        return dirsToCheck.some(dir => filePath.includes(dir));
+      }
+
+      function isCloudDoc(file, connector, type) {
+        return (
+          file.src.component === 'redpanda-cloud' &&
+          file.path.includes(`connect/components/${type}s/${connector}.adoc`)
+        );
+      }
+
       // Look for both Redpanda Connect and Cloud URLs
       for (const file of pages) {
-        const component = file.src.component;
-        const filePath = file.path;
+        const { component } = file.src;      // such as 'redpanda-connect'
+        const { path: filePath } = file;     // such as modules/.../pages/sinks/foo.adoc
 
         if (
           component === 'redpanda-connect' &&
           filePath.endsWith(`/${connector}.adoc`) &&
-          filePath.includes(`pages/${type}s/`)
+          isConnectorDocPath(filePath, type)
         ) {
           redpandaConnectUrl = file.pub.url;
         }
 
-        // Only check for Redpanda Cloud URLs if cloud is supported
-        if (
-          is_cloud_supported === 'y' &&
-          component === 'redpanda-cloud' &&
-          filePath.endsWith(`/${connector}.adoc`) &&
-          filePath.includes(`${type}s/`)
-        ) {
+        // -------------------------------------------------
+        // Redpanda Cloud (only if cloud supported)
+        // -------------------------------------------------
+        if (is_cloud_supported === 'y' && isCloudDoc(file, connector, type)) {
           redpandaCloudUrl = file.pub.url;
         }
       }
 
-      // Log a warning if neither URL was found and the component is not deprecated
       if (
         deprecated !== 'y' &&
         !connector.includes('sql_driver') &&
         !redpandaConnectUrl &&
-        (!redpandaCloudUrl && is_cloud_supported === 'y')
+        !(is_cloud_supported === 'y' && redpandaCloudUrl)
       ) {
-        logger.warn(`Docs missing for: ${connector} of type: ${type}`);
+        logger.warn(`Self-Managed docs missing for: ${connector} of type: ${type}`);
       }
 
+      if (
+        is_cloud_supported === 'y' &&
+        !redpandaCloudUrl &&
+        redpandaConnectUrl
+      ) {
+        logger.warn(`Cloud docs missing for: ${connector} of type: ${type}`);
+      }
 
       // Return the translated and enriched row
       return {

package/macros/badge.js

@@ -0,0 +1,21 @@
+'use strict';
+
+module.exports.register = function (registry) {
+  registry.inlineMacro(function () {
+    const self = this;
+    self.named('badge');
+    self.process((parent, target, attrs) => {
+      const label = attrs.label || 'label';
+      const className = `badge--${label.toLowerCase().replace(/\s+/g, '-')}`;
+      const isLarge = attrs.size === 'large';
+      const sizeClass = isLarge ? 'badge--large' : '';
+      const tooltip = attrs.tooltip;
+      const tooltipAttr = tooltip ? ` data-tooltip="${tooltip}"` : '';
+
+      // Add brackets if not large
+      const renderedLabel = isLarge ? label : `(${label})`;
+
+      return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
+    });
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.6.1",
+  "version": "4.6.3",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -57,7 +57,8 @@
     "./macros/glossary": "./macros/glossary.js",
     "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",
-    "./macros/helm-ref": "./macros/helm-ref.js"
+    "./macros/helm-ref": "./macros/helm-ref.js",
+    "./macros/badge": "./macros/badge.js"
   },
   "files": [
     "extensions",

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

@@ -35,47 +35,99 @@ function registerPartial(name, filePath) {
 
 /**
  * Deep-merge `overrides` into `target`. Only 'description', 'type',
- * plus nested array/object entries get overridden; other keys remain intact.
+ * 'annotated_field', 'examples', and known nested fields are overridden.
  */
 function mergeOverrides(target, overrides) {
   if (!overrides || typeof overrides !== 'object') return target;
   if (!target || typeof target !== 'object') {
     throw new Error('Target must be a valid object');
   }
+
+  const scalarKeys = ['description', 'type', 'annotated_field', 'version'];
+
   for (const key in overrides) {
+    // === Handle annotated_options ===
+    if (key === 'annotated_options' && Array.isArray(overrides[key]) && Array.isArray(target[key])) {
+      const overrideMap = new Map(overrides[key].map(([name, desc]) => [name, desc]));
+
+      target[key] = target[key].map(([name, desc]) => {
+        if (overrideMap.has(name)) {
+          return [name, overrideMap.get(name)];
+        }
+        return [name, desc];
+      });
+
+      const existingNames = new Set(target[key].map(([name]) => name));
+      for (const [name, desc] of overrides[key]) {
+        if (!existingNames.has(name)) {
+          target[key].push([name, desc]);
+        }
+      }
+      continue;
+    }
+
+    // === Handle examples ===
+    if (key === 'examples' && Array.isArray(overrides[key]) && Array.isArray(target[key])) {
+      const overrideMap = new Map(overrides[key].map(o => [o.title, o]));
+
+      target[key] = target[key].map(example => {
+        const override = overrideMap.get(example.title);
+        if (override) {
+          return {
+            ...example,
+            ...(override.summary && { summary: override.summary }),
+            ...(override.config && { config: override.config }),
+          };
+        }
+        return example;
+      });
+
+      const existingTitles = new Set(target[key].map(e => e.title));
+      for (const example of overrides[key]) {
+        if (!existingTitles.has(example.title)) {
+          target[key].push(example);
+        }
+      }
+      continue;
+    }
+
+    // === Merge arrays of objects with .name ===
     if (Array.isArray(target[key]) && Array.isArray(overrides[key])) {
-      // Merge two parallel arrays by matching items on `.name`
       target[key] = target[key].map(item => {
         const overrideItem = overrides[key].find(o => o.name === item.name);
         if (overrideItem) {
-          // Overwrite description/type if present
-          ['description', 'type'].forEach(field => {
+          scalarKeys.forEach(field => {
             if (Object.hasOwn(overrideItem, field)) {
               item[field] = overrideItem[field];
             }
           });
-          // Copy through selfManagedOnly flag
           if (Object.hasOwn(overrideItem, 'selfManagedOnly')) {
             item.selfManagedOnly = overrideItem.selfManagedOnly;
           }
-          // Recurse for nested children
-          item = mergeOverrides(item, overrideItem);
+          return mergeOverrides(item, overrideItem);
         }
         return item;
       });
-    } else if (
+      continue;
+    }
+
+    // === Merge nested objects ===
+    if (
       typeof target[key] === 'object' &&
       typeof overrides[key] === 'object' &&
       !Array.isArray(target[key]) &&
       !Array.isArray(overrides[key])
     ) {
-      // Deep-merge plain objects
       target[key] = mergeOverrides(target[key], overrides[key]);
-    } else if (['description', 'type'].includes(key) && Object.hasOwn(overrides, key)) {
-      // Overwrite the primitive
+      continue;
+    }
+
+    // === Overwrite scalar keys ===
+    if (scalarKeys.includes(key) && Object.hasOwn(overrides, key)) {
       target[key] = overrides[key];
     }
   }
+
   return target;
 }
 
@@ -185,7 +237,7 @@ async function generateRpcnConnectorDocs(options) {
           partialFiles.push(path.relative(process.cwd(), fPath));
         }
 
-        if (examplesOut.trim()) {
+        if (examplesOut.trim() && type !== 'bloblang-functions' && type !== 'bloblang-methods') {
           const ePath = path.join(examplesOutRoot, type, `${name}.adoc`);
           fs.mkdirSync(path.dirname(ePath), { recursive: true });
           fs.writeFileSync(ePath, examplesOut);

package/tools/redpanda-connect/helpers/renderConnectFields.js

@@ -26,7 +26,7 @@ module.exports = function renderConnectFields(children, prefix = '') {
   sorted.forEach(child => {
     if (child.is_deprecated || !child.name) return;
 
-    // Normalize type
+    // Normalize type: arrays and unknown-map as object
     let displayType;
     if (child.type === 'string' && child.kind === 'array') {
       displayType = 'array';
@@ -56,27 +56,49 @@ module.exports = function renderConnectFields(children, prefix = '') {
 
     block += `*Type*: \`${displayType}\`\n\n`;
 
-    // Default
-    if (child.type !== 'object' && child.default !== undefined) {
-      if (typeof child.default !== 'object') {
-        const display = child.default === '' ? '""' : String(child.default);
-        block += `*Default*: \`${display}\`\n\n`;
-      } else {
+    // Default value
+    if (child.default !== undefined) {
+      // Empty array
+      if (Array.isArray(child.default) && child.default.length === 0) {
+        block += `*Default*: \`[]\`\n\n`;
+      }
+      // Empty object
+      else if (
+        child.default !== null &&
+        typeof child.default === 'object' &&
+        !Array.isArray(child.default) &&
+        Object.keys(child.default).length === 0
+      ) {
+        block += `*Default*: \`{}\`\n\n`;
+      }
+      // Complex object/array
+      else if (typeof child.default === 'object') {
         const defYaml = yaml.stringify(child.default).trim();
         block += `*Default*:\n[source,yaml]\n----\n${defYaml}\n----\n\n`;
       }
+      // Primitive
+      else {
+        const display = typeof child.default === 'string'
+          ? (child.default.startsWith('"') && child.default.endsWith('"')
+              ? child.default
+              : child.default === ''
+              ? '""'
+              : child.default)
+          : String(child.default);
+        block += `*Default*: \`${display}\`\n\n`;
+      }
     }
 
-    // Annotated options
+    // Annotated options table
     if (child.annotated_options && child.annotated_options.length) {
-      block += `[cols=\"1m,2a\"]\n|===\n|Option |Summary\n\n`;
+      block += `[cols="1m,2a"]\n|===\n|Option |Summary\n\n`;
       child.annotated_options.forEach(([opt, summary]) => {
         block += `|${opt}\n|${summary}\n\n`;
       });
       block += `|===\n\n`;
     }
 
-    // Options list
+    // Simple options list
     if (child.options && child.options.length) {
       block += `*Options*: ${child.options.map(opt => `\`${opt}\``).join(', ')}\n\n`;
     }
@@ -84,54 +106,27 @@ module.exports = function renderConnectFields(children, prefix = '') {
     // Examples
     if (child.examples && child.examples.length) {
       block += `[source,yaml]\n----\n# Examples:\n`;
-      if (child.type === 'string') {
-        if (child.kind === 'array') {
-          block += renderYamlList(child.name, child.examples);
-        } else {
-          child.examples.forEach(example => {
-            if (typeof example === 'string' && example.includes('\n')) {
-              block += `${child.name}: |-\n`;
-              block += example.split('\n').map(line => '  ' + line).join('\n') + '\n';
-            } else {
-              block += `${child.name}: \`${example}\`\n`;
-            }
-          });
-          block += '\n';
-        }
-      } else if (child.type === 'processor') {
-        if (child.kind === 'array') {
-          block += renderYamlList(child.name, child.examples);
-        } else {
-          child.examples.forEach(example => {
-            block += `${child.name}: \`${String(example)}\`\n`;
-          });
-          block += '\n';
-        }
-      } else if (child.type === 'object') {
-        if (child.kind === 'array') {
-          block += renderYamlList(child.name, child.examples);
-        } else {
-          child.examples.forEach(example => {
-            if (typeof example === 'object') {
-              const snippet = yaml.stringify(example).trim();
-              block += `${child.name}:\n`;
-              block += snippet.split('\n').map(line => '  ' + line).join('\n') + '\n';
-            } else {
-              block += `${child.name}: \`${String(example)}\`\n`;
-            }
-          });
-          block += '\n';
-        }
+      if (child.kind === 'array') {
+        block += renderYamlList(child.name, child.examples);
       } else {
         child.examples.forEach(example => {
-          block += `${child.name}: \`${String(example)}\`\n`;
+          if (typeof example === 'object') {
+            const snippet = yaml.stringify(example).trim();
+            block += `${child.name}:\n`;
+            block += snippet.split('\n').map(line => '  ' + line).join('\n') + '\n';
+          } else if (typeof example === 'string' && example.includes('\n')) {
+            block += `${child.name}: |-\n`;
+            block += example.split('\n').map(line => '  ' + line).join('\n') + '\n';
+          } else {
+            // Primitive values
+            block += `${child.name}: ${example}\n`;
+          }
         });
-        block += '\n';
       }
       block += `----\n\n`;
     }
 
-    // Nested
+    // Nested children
     if (child.children && child.children.length) {
       block += renderConnectFields(child.children, currentPath);
     }

package/tools/redpanda-connect/helpers/renderLeafField.js

@@ -31,34 +31,57 @@ module.exports = function renderLeafField(field, indentLevel) {
 
   // If a default is provided, use it:
   if (field.default !== undefined) {
-    // If default is itself an object or array → dump as YAML block
+    // Empty array inline
+    if (Array.isArray(field.default) && field.default.length === 0) {
+      return `${indent}${name}: []`;
+    }
+    // Empty object inline
+    if (
+      field.default !== null &&
+      typeof field.default === 'object' &&
+      !Array.isArray(field.default) &&
+      Object.keys(field.default).length === 0
+    ) {
+      return `${indent}${name}: {}`;
+    }
+
+    // Complex object/array: dump as YAML block
     if (typeof field.default === 'object') {
-        try {
-          // Turn the object/array into a YAML string. We also need to indent that block
-          const rawYaml = yaml.stringify(field.default).trim();
-          // Indent each line of rawYaml by (indentLevel + 2) spaces:
-          const indentedYaml = rawYaml
+      try {
+        const rawYaml = yaml.stringify(field.default).trim();
+        const indentedYaml = rawYaml
           .split('\n')
           .map(line => ' '.repeat(indentLevel + 2) + line)
           .join('\n');
-          return `${indent}${name}:\n${indentedYaml}`;
-        } catch (error) {
-          console.warn(`Failed to serialize default value for field ${field.name}:`, error);
-          return `${indent}${name}: {} # Error serializing default value`;
-        }
+        return `${indent}${name}:\n${indentedYaml}`;
+      } catch (error) {
+        console.warn(`Failed to serialize default for ${field.name}:`, error);
+        return `${indent}${name}: {} # Error serializing default`;
+      }
     }
 
-    // Otherwise, default is a primitive (string/number/bool)
-    if (field.type === 'string') {
-      return `${indent}${name}: ${yaml.stringify(field.default)}`;
+    // Primitive default: string, number, boolean
+    let value;
+    if (typeof field.default === 'string') {
+      // Preserve existing quotes
+      if (field.default.startsWith('"') && field.default.endsWith('"')) {
+        value = field.default;
+      } else if (field.default === '') {
+        value = '""';
+      } else {
+        value = field.default;
+      }
+    } else {
+      value = String(field.default);
     }
-    return `${indent}${name}: ${field.default}`;
+
+    return `${indent}${name}: ${value}`;
   }
 
-  // No default → choose representation based on kind
+  // No default → choose representation
   if (field.kind === 'array') {
     return `${indent}${name}: [] ${comment}`;
   } else {
     return `${indent}${name}: "" ${comment}`;
   }
-}
+};

package/tools/redpanda-connect/helpers/renderYamlList.js

@@ -12,13 +12,27 @@ module.exports = function renderYamlList(name, exampleGroups) {
   exampleGroups.forEach(group => {
     const items = Array.isArray(group) ? group : [group];
     items.forEach(item => {
-      const snippet = yaml.stringify(item).trim();
-      const lines = snippet.split('\n');
-      out += lines
-        .map((line, idx) => (idx === 0 ? `  - ${line}` : `    ${line}`))
-        .join('\n') + '\n';
+      // Scalars
+      if (typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') {
+        let value = String(item);
+        // Quote when needed: already-quoted scalars stay as-is; otherwise quote `*`
+        // and any value containing YAML-special characters.
+        if (!(value.startsWith('"') && value.endsWith('"'))) {
+          if (value === '*' || /[:\[\]\{\},&>|%@`]/.test(value)) {
+            value = `"${value}"`;
+          }
+        }
+        out += `  - ${value}\n`;
+      } else {
+        // Objects/arrays: stringify with indentation
+        const snippet = yaml.stringify(item).trim();
+        const lines = snippet.split('\n');
+        out += lines
+          .map((line, idx) => (idx === 0 ? `  - ${line}` : `    ${line}`))
+          .join('\n') + '\n';
+      }
     });
     out += '\n';
   });
   return out;
-}
+};

package/macros/enterprise-label.js

@@ -1,11 +0,0 @@
-'use strict';
-
-module.exports.register = function (registry) {
-  registry.inlineMacro(function () {
-    const self = this;
-    self.named('enterprise-label');
-    self.process((parent, target, attrs) => {
-      return `<span class="inline-enterprise-label">Enterprise</span>`;
-    });
-  });
-};