@redpanda-data/docs-extensions-and-macros 4.15.7 → 4.15.8

package/package.json

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

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

@@ -472,6 +472,28 @@ async function generateRpcnConnectorDocs(options) {
       if (!Array.isArray(items)) continue;
       const outRoot = path.join(outputRoot, folder);
       fs.mkdirSync(outRoot, { recursive: true });
+
+      // Get current item names
+      const currentNames = new Set(items.filter(fn => fn.name).map(fn => fn.name));
+
+      // Delete partials that no longer exist in the data
+      if (fs.existsSync(outRoot)) {
+        const existingFiles = fs.readdirSync(outRoot).filter(f => f.endsWith('.adoc'));
+        for (const file of existingFiles) {
+          const name = file.replace('.adoc', '');
+          // Skip hand-authored files (by convention, start with underscore)
+          if (name.startsWith('_')) {
+            console.log(`Skipping hand-authored file: ${file}`);
+            continue;
+          }
+          if (!currentNames.has(name)) {
+            const filePath = path.join(outRoot, file);
+            fs.unlinkSync(filePath);
+            console.log(`Deleted removed ${folder} partial: ${file}`);
+          }
+        }
+      }
+
       // Use custom or default template
       const bloblangTemplatePath = templateBloblang || path.resolve(__dirname, './templates/bloblang-function.hbs');
       const bloblangTemplate = handlebars.compile(fs.readFileSync(bloblangTemplatePath, 'utf8'));
@@ -484,6 +506,71 @@ async function generateRpcnConnectorDocs(options) {
         partialFiles.push(path.relative(process.cwd(), outPath));
       }
     }
+
+    // Generate overview pages for Bloblang methods and functions
+    const guidesRoot = path.join(process.cwd(), 'modules/guides/pages/bloblang');
+    fs.mkdirSync(guidesRoot, { recursive: true });
+
+    // Generate methods.adoc with categorized methods
+    if (dataObj['bloblang-methods']) {
+      const methodsData = dataObj['bloblang-methods'];
+      const categoriesMap = new Map();
+
+      // Extract categories and their methods
+      for (const method of methodsData) {
+        if (!method.name || !method.categories || !Array.isArray(method.categories)) continue;
+
+        for (const cat of method.categories) {
+          const categoryName = cat.Category;
+          if (!categoryName) continue;
+
+          if (!categoriesMap.has(categoryName)) {
+            categoriesMap.set(categoryName, []);
+          }
+          categoriesMap.get(categoryName).push(method.name);
+        }
+      }
+
+      // Sort categories and prepare data for template
+      const categories = Array.from(categoriesMap.entries())
+        .map(([name, methods]) => ({
+          name,
+          methods: methods.sort()
+        }))
+        .sort((a, b) => {
+          // Special ordering: General first, Deprecated last
+          if (a.name === 'General') return -1;
+          if (b.name === 'General') return 1;
+          if (a.name === 'Deprecated') return 1;
+          if (b.name === 'Deprecated') return -1;
+          return a.name.localeCompare(b.name);
+        });
+
+      const methodsTemplatePath = path.resolve(__dirname, './templates/bloblang-methods-overview.hbs');
+      const methodsTemplate = handlebars.compile(fs.readFileSync(methodsTemplatePath, 'utf8'));
+      const methodsAdoc = methodsTemplate({ categories });
+      const methodsOutPath = path.join(guidesRoot, 'methods.adoc');
+      fs.writeFileSync(methodsOutPath, methodsAdoc, 'utf8');
+      console.log('Generated methods.adoc overview page');
+      partialFiles.push(path.relative(process.cwd(), methodsOutPath));
+    }
+
+    // Generate functions.adoc with all functions
+    if (dataObj['bloblang-functions']) {
+      const functionsData = dataObj['bloblang-functions'];
+      const functionNames = functionsData
+        .filter(fn => fn.name)
+        .map(fn => fn.name)
+        .sort();
+
+      const functionsTemplatePath = path.resolve(__dirname, './templates/bloblang-functions-overview.hbs');
+      const functionsTemplate = handlebars.compile(fs.readFileSync(functionsTemplatePath, 'utf8'));
+      const functionsAdoc = functionsTemplate({ functions: functionNames });
+      const functionsOutPath = path.join(guidesRoot, 'functions.adoc');
+      fs.writeFileSync(functionsOutPath, functionsAdoc, 'utf8');
+      console.log('Generated functions.adoc overview page');
+      partialFiles.push(path.relative(process.cwd(), functionsOutPath));
+    }
   }
 
   // Common/Advanced config snippet YAMLs in modules/components/examples

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

@@ -1,10 +1,30 @@
 // Bloblang example formatting helper for Handlebars
 function bloblangExample(example) {
   if (typeof example === 'object' && example !== null && example.mapping) {
+    let leadIn = '';
     let codeBlock = '';
+
+    // Extract summary as lead-in prose (not a comment in code)
     if (example.summary && example.summary.trim()) {
-      codeBlock += `# ${example.summary.trim().replace(/\n/g, '\n# ')}\n\n`;
+      let summary = example.summary.trim();
+
+      // Convert Markdown headings to AsciiDoc
+      // ##### Heading -> ==== Heading (H5 -> H4 in AsciiDoc)
+      summary = summary.replace(/^#####\s+(.+)$/gm, '==== $1');
+      // #### Heading -> === Heading (H4 -> H3 in AsciiDoc)
+      summary = summary.replace(/^####\s+(.+)$/gm, '=== $1');
+      // ### Heading -> == Heading (H3 -> H2 in AsciiDoc)
+      summary = summary.replace(/^###\s+(.+)$/gm, '== $1');
+
+      // Ensure lead-in ends with a colon (replace period/exclamation/question mark if present)
+      if (summary.endsWith('.') || summary.endsWith('!') || summary.endsWith('?')) {
+        summary = summary.slice(0, -1) + ':';
+      } else if (!summary.endsWith(':')) {
+        summary += ':';
+      }
+      leadIn = summary + '\n\n';
     }
+
     if (typeof example.mapping === 'string') {
       codeBlock += example.mapping.trim() + '\n';
     }
@@ -15,7 +35,7 @@ function bloblangExample(example) {
         }
       }
     }
-    return `[,coffeescript]\n----\n${codeBlock.trim()}\n----\n`;
+    return `${leadIn}[,bloblang]\n----\n${codeBlock.trim()}\n----\n`;
   } else {
     let exStr = '';
     if (typeof example === 'string') {
@@ -35,7 +55,7 @@ function bloblangExample(example) {
     } else {
       exStr = String(example);
     }
-    return `[source,coffeescript]\n----\n${exStr}\n----\n`;
+    return `[source,bloblang]\n----\n${exStr}\n----\n`;
   }
 }
 

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

@@ -0,0 +1,27 @@
+/**
+ * Ensures a text string ends with a period (or other terminal punctuation).
+ * Used for normalizing Bloblang descriptions.
+ *
+ * @param {string} text - The text to process
+ * @returns {string} Text ending with appropriate punctuation
+ */
+function ensurePeriod(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return text;
+  }
+
+  // Check if already ends with terminal punctuation
+  if (trimmed.endsWith('.') || trimmed.endsWith('!') || trimmed.endsWith('?')) {
+    return text;
+  }
+
+  // Add period
+  return text.trim() + '.';
+}
+
+module.exports = ensurePeriod;

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

@@ -0,0 +1,7 @@
+// Check if any parameters are optional
+function hasOptionalParams(params) {
+  if (!Array.isArray(params)) return false;
+  return params.some(param => param.is_optional);
+}
+
+module.exports = hasOptionalParams;

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

@@ -17,4 +17,7 @@ module.exports = {
   commonConfig:           require('./commonConfig.js'),
   advancedConfig:         require('./advancedConfig.js'),
   bloblangExample:        require('./bloblangExample.js'),
+  hasOptionalParams:      require('./hasOptionalParams.js'),
+  ensurePeriod:           require('./ensurePeriod.js'),
+  toSentenceCase:         require('./toSentenceCase.js'),
 };

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

@@ -0,0 +1,69 @@
+'use strict'
+
+/**
+ * Convert a string to sentence case, preserving acronyms and proper nouns
+ * @param {string} text - The text to convert
+ * @returns {string} The text in sentence case
+ */
+function toSentenceCase(text) {
+  if (!text) return ''
+
+  // Map of exact word matches to preserve (case-sensitive)
+  const exactPreserve = new Map([
+    ['geoip', 'GeoIP'],
+    ['GEOIP', 'GeoIP'],
+    ['GeoIP', 'GeoIP']
+  ])
+
+  // List of acronyms to preserve (will be uppercased)
+  const preserveWords = new Set([
+    'SQL',
+    'JSON',
+    'JWT',
+    'XML',
+    'HTML',
+    'URL',
+    'URI',
+    'HTTP',
+    'HTTPS',
+    'TLS',
+    'SSL',
+    'AWS',
+    'GCP',
+    'API',
+    'ID',
+    'UUID',
+    'CSV'
+  ])
+
+  // Split into words
+  const words = text.split(/\s+/)
+
+  return words.map((word, index) => {
+    // Check if word is in exact preserve map first
+    if (exactPreserve.has(word) || exactPreserve.has(word.toLowerCase()) || exactPreserve.has(word.toUpperCase())) {
+      const key = exactPreserve.has(word) ? word : (exactPreserve.has(word.toLowerCase()) ? word.toLowerCase() : word.toUpperCase())
+      return exactPreserve.get(key)
+    }
+
+    // Check if word is in preserve list (case-insensitive check)
+    if (preserveWords.has(word.toUpperCase())) {
+      return word.toUpperCase()
+    }
+
+    // Check if word contains special characters like &
+    if (word === '&') {
+      return word
+    }
+
+    // First word: capitalize first letter, lowercase rest
+    if (index === 0) {
+      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+    }
+
+    // Subsequent words: lowercase
+    return word.toLowerCase()
+  }).join(' ')
+}
+
+module.exports = toSentenceCase

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

@@ -3,6 +3,118 @@
  * Outputs a console-parseable format for GitHub Actions
  */
 
+/**
+ * Render Bloblang changes section for PR summary
+ * @param {object} data - Bloblang change data
+ * @param {array} data.newMethods - Array of new methods (with .name and optional .version)
+ * @param {array} data.newFunctions - Array of new functions (with .name and optional .version)
+ * @param {array} data.removedMethods - Array of removed methods
+ * @param {array} data.removedFunctions - Array of removed functions
+ * @param {array} data.deprecatedMethods - Array of deprecated methods
+ * @param {array} data.deprecatedFunctions - Array of deprecated functions
+ * @param {boolean} includeVersion - Whether to include version info in output
+ * @returns {array} Array of lines to add to the summary
+ */
+function renderBloblangChanges(data, includeVersion = false) {
+  const lines = [];
+  const {
+    newMethods = [],
+    newFunctions = [],
+    removedMethods = [],
+    removedFunctions = [],
+    deprecatedMethods = [],
+    deprecatedFunctions = []
+  } = data;
+
+  const hasChanges = newMethods.length > 0 || newFunctions.length > 0 ||
+                     removedMethods.length > 0 || removedFunctions.length > 0 ||
+                     deprecatedMethods.length > 0 || deprecatedFunctions.length > 0;
+
+  if (!hasChanges) {
+    return lines;
+  }
+
+  lines.push('**Update Bloblang Guide Pages:**');
+  lines.push('');
+
+  if (newMethods.length > 0) {
+    lines.push(`New methods to add to \`modules/guides/pages/bloblang/methods.adoc\` (${newMethods.length}):`);
+    newMethods.forEach(method => {
+      const versionInfo = includeVersion && method.version ? ` — introduced in **${method.version}**` : '';
+      const name = typeof method === 'string' ? method : method.name;
+      lines.push(`- [ ] \`${name}\`${versionInfo}`);
+    });
+    lines.push('');
+  }
+
+  if (newFunctions.length > 0) {
+    lines.push(`New functions to add to \`modules/guides/pages/bloblang/functions.adoc\` (${newFunctions.length}):`);
+    newFunctions.forEach(func => {
+      const versionInfo = includeVersion && func.version ? ` — introduced in **${func.version}**` : '';
+      const name = typeof func === 'string' ? func : func.name;
+      lines.push(`- [ ] \`${name}\`${versionInfo}`);
+    });
+    lines.push('');
+  }
+
+  if (removedMethods.length > 0) {
+    lines.push(`Removed methods to delete from \`modules/guides/pages/bloblang/methods.adoc\` (${removedMethods.length}):`);
+    removedMethods.forEach(method => {
+      const versionInfo = includeVersion && method.version ? ` — removed in **${method.version}**` : '';
+      const name = typeof method === 'string' ? method : method.name;
+      lines.push(`- [ ] \`${name}\`${versionInfo}`);
+    });
+    lines.push('');
+  }
+
+  if (removedFunctions.length > 0) {
+    lines.push(`Removed functions to delete from \`modules/guides/pages/bloblang/functions.adoc\` (${removedFunctions.length}):`);
+    removedFunctions.forEach(func => {
+      const versionInfo = includeVersion && func.version ? ` — removed in **${func.version}**` : '';
+      const name = typeof func === 'string' ? func : func.name;
+      lines.push(`- [ ] \`${name}\`${versionInfo}`);
+    });
+    lines.push('');
+  }
+
+  if (deprecatedMethods.length > 0) {
+    lines.push(`Deprecated methods - add deprecation notice to \`modules/guides/pages/bloblang/methods.adoc\` (${deprecatedMethods.length}):`);
+    deprecatedMethods.forEach(method => {
+      const versionInfo = includeVersion && method.version ? ` — deprecated in **${method.version}**` : '';
+      const name = typeof method === 'string' ? method : method.name;
+      lines.push(`- [ ] \`${name}\`${versionInfo}`);
+    });
+    lines.push('');
+  }
+
+  if (deprecatedFunctions.length > 0) {
+    lines.push(`Deprecated functions - add deprecation notice to \`modules/guides/pages/bloblang/functions.adoc\` (${deprecatedFunctions.length}):`);
+    deprecatedFunctions.forEach(func => {
+      const versionInfo = includeVersion && func.version ? ` — deprecated in **${func.version}**` : '';
+      const name = typeof func === 'string' ? func : func.name;
+      lines.push(`- [ ] \`${name}\`${versionInfo}`);
+    });
+    lines.push('');
+  }
+
+  lines.push('**How to add includes:**');
+  lines.push('');
+  lines.push('For methods, find the appropriate category section in `methods.adoc` and add:');
+  lines.push('```asciidoc');
+  lines.push('include::redpanda-connect:partial$bloblang-methods/method_name.adoc[leveloffset=+2]');
+  lines.push('```');
+  lines.push('');
+  lines.push('For functions, add to the Functions section in `functions.adoc`:');
+  lines.push('```asciidoc');
+  lines.push('include::redpanda-connect:partial$bloblang-functions/function_name.adoc[leveloffset=+2]');
+  lines.push('```');
+  lines.push('');
+  lines.push('**Note:** Partials are auto-generated. Includes must be added manually in alphabetical order within their section.');
+  lines.push('');
+
+  return lines;
+}
+
 /**
  * Generate PR summary for multiple releases
  * @param {object} masterDiff - Master diff with releases array
@@ -21,9 +133,9 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
 
   lines.push('<!-- PR_SUMMARY_START -->');
   lines.push('');
-  lines.push('## 📊 Redpanda Connect Documentation Update');
+  lines.push('## Redpanda Connect Documentation Update');
   lines.push('');
-  lines.push(`**📦 Multi-Release Update:** ${startVersion} → ${endVersion}`);
+  lines.push(`**Multi-Release Update:** ${startVersion} → ${endVersion}`);
   lines.push(`**Releases Processed:** ${processedReleases}`);
 
   if (binaryAnalysis) {
@@ -44,10 +156,10 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     lines.push(`- **${total.newFields}** new fields across ${total.releaseCount || 0} release(s)`);
   }
   if (total.removedComponents > 0) {
-    lines.push(`- **${total.removedComponents}** removed connectors ⚠️`);
+    lines.push(`- **${total.removedComponents}** removed connectors`);
   }
   if (total.removedFields > 0) {
-    lines.push(`- **${total.removedFields}** removed fields ⚠️`);
+    lines.push(`- **${total.removedFields}** removed fields`);
   }
   if (total.deprecatedComponents > 0) {
     lines.push(`- **${total.deprecatedComponents}** deprecated connectors`);
@@ -56,7 +168,19 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     lines.push(`- **${total.deprecatedFields}** deprecated fields`);
   }
   if (total.changedDefaults > 0) {
-    lines.push(`- **${total.changedDefaults}** changed default values ⚠️`);
+    lines.push(`- **${total.changedDefaults}** changed default values`);
+  }
+  if (total.newBloblangMethods > 0) {
+    lines.push(`- **${total.newBloblangMethods}** new Bloblang methods`);
+  }
+  if (total.removedBloblangMethods > 0) {
+    lines.push(`- **${total.removedBloblangMethods}** removed Bloblang methods`);
+  }
+  if (total.newBloblangFunctions > 0) {
+    lines.push(`- **${total.newBloblangFunctions}** new Bloblang functions`);
+  }
+  if (total.removedBloblangFunctions > 0) {
+    lines.push(`- **${total.removedBloblangFunctions}** removed Bloblang functions`);
   }
 
   lines.push('');
@@ -76,7 +200,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
 
   for (const release of releases) {
     const releaseNotesUrl = `https://github.com/redpanda-data/connect/releases/tag/v${release.toVersion}`;
-    lines.push(`#### 🔖 Version ${release.toVersion}`);
+    lines.push(`#### Version ${release.toVersion}`);
     lines.push(`> [Release notes](${releaseNotesUrl})`);
     lines.push('');
 
@@ -140,7 +264,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     // Removed components
     const removedComponents = details.removedComponents || [];
     if (summary.removedComponents > 0 && removedComponents.length > 0) {
-      lines.push(`**⚠️ Removed Connectors (${summary.removedComponents}):**`);
+      lines.push(`**Removed Connectors (${summary.removedComponents}):**`);
       lines.push('');
       removedComponents.forEach(comp => {
         lines.push(`- \`${comp.name}\` (${comp.type})`);
@@ -151,7 +275,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     // Removed fields
     const removedFields = details.removedFields || [];
     if (summary.removedFields > 0 && removedFields.length > 0) {
-      lines.push(`**⚠️ Removed Fields (${summary.removedFields}):**`);
+      lines.push(`**Removed Fields (${summary.removedFields}):**`);
       lines.push('');
       lines.push('| Component | Field |');
       lines.push('|-----------|-------|');
@@ -176,7 +300,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     // Changed defaults
     const changedDefaults = details.changedDefaults || [];
     if (summary.changedDefaults > 0 && changedDefaults.length > 0) {
-      lines.push(`**⚠️ Changed Defaults (${summary.changedDefaults}):**`);
+      lines.push(`**Changed Defaults (${summary.changedDefaults}):**`);
       lines.push('');
       lines.push('| Component | Field | Old Default | New Default |');
       lines.push('|-----------|-------|-------------|-------------|');
@@ -192,7 +316,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
   // Writer action items (aggregate)
   lines.push('---');
   lines.push('');
-  lines.push('### ✍️ Writer Action Items');
+  lines.push('### Writer Action Items');
   lines.push('');
 
   // Collect all new connectors across all releases with full details
@@ -200,6 +324,12 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
   const allRemovedConnectors = [];
   const allDeprecatedFields = [];
   const allChangedDefaults = [];
+  const allNewBloblangMethods = [];
+  const allRemovedBloblangMethods = [];
+  const allNewBloblangFunctions = [];
+  const allRemovedBloblangFunctions = [];
+  const allDeprecatedBloblangMethods = [];
+  const allDeprecatedBloblangFunctions = [];
 
   releases.forEach(release => {
     const details = release.details || {};
@@ -253,6 +383,48 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
         version: release.toVersion
       });
     });
+
+    // New/removed Bloblang methods
+    (details.newBloblangMethods || []).forEach(methodName => {
+      allNewBloblangMethods.push({
+        name: methodName,
+        version: release.toVersion
+      });
+    });
+    (details.removedBloblangMethods || []).forEach(methodName => {
+      allRemovedBloblangMethods.push({
+        name: methodName,
+        version: release.toVersion
+      });
+    });
+
+    // New/removed Bloblang functions
+    (details.newBloblangFunctions || []).forEach(funcName => {
+      allNewBloblangFunctions.push({
+        name: funcName,
+        version: release.toVersion
+      });
+    });
+    (details.removedBloblangFunctions || []).forEach(funcName => {
+      allRemovedBloblangFunctions.push({
+        name: funcName,
+        version: release.toVersion
+      });
+    });
+
+    // Deprecated Bloblang methods/functions
+    (details.deprecatedBloblangMethods || []).forEach(methodName => {
+      allDeprecatedBloblangMethods.push({
+        name: methodName,
+        version: release.toVersion
+      });
+    });
+    (details.deprecatedBloblangFunctions || []).forEach(funcName => {
+      allDeprecatedBloblangFunctions.push({
+        name: funcName,
+        version: release.toVersion
+      });
+    });
   });
 
   // Priority 1: New connectors needing documentation
@@ -292,7 +464,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
 
   // Priority 2: Removed connectors needing migration docs
   if (allRemovedConnectors.length > 0) {
-    lines.push('**⚠️ Update Migration Guide for Removed Connectors:**');
+    lines.push('**Update Migration Guide for Removed Connectors:**');
     lines.push('');
     allRemovedConnectors.forEach(conn => {
       lines.push(`- [ ] \`${conn.name}\` ${conn.type} — removed in **${conn.version}**`);
@@ -302,7 +474,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
 
   // Priority 3: Deprecated fields needing docs update
   if (allDeprecatedFields.length > 0) {
-    lines.push('**📋 Update Docs for Deprecated Fields:**');
+    lines.push('**Update Docs for Deprecated Fields:**');
     lines.push('');
     allDeprecatedFields.forEach(field => {
       const guidance = field.description ? ` (${truncateToSentence(field.description, 1)})` : '';
@@ -313,7 +485,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
 
   // Priority 4: Changed defaults that may affect users
   if (allChangedDefaults.length > 0) {
-    lines.push('**⚠️ Review Changed Defaults for Breaking Changes:**');
+    lines.push('**Review Changed Defaults for Breaking Changes:**');
     lines.push('');
     allChangedDefaults.forEach(change => {
       const oldVal = change.oldDefault !== undefined ? JSON.stringify(change.oldDefault) : 'none';
@@ -323,6 +495,17 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
     lines.push('');
   }
 
+  // Bloblang methods and functions
+  const bloblangLines = renderBloblangChanges({
+    newMethods: allNewBloblangMethods,
+    newFunctions: allNewBloblangFunctions,
+    removedMethods: allRemovedBloblangMethods,
+    removedFunctions: allRemovedBloblangFunctions,
+    deprecatedMethods: allDeprecatedBloblangMethods,
+    deprecatedFunctions: allDeprecatedBloblangFunctions
+  }, true); // includeVersion = true for multi-version summaries
+  lines.push(...bloblangLines);
+
   // Add commercial name reminder if there are new connectors
   if (allNewConnectors.length > 0) {
     lines.push('---');
@@ -368,7 +551,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   // Single version format (original logic)
   // Quick Summary Section
-  lines.push('## 📊 Redpanda Connect Documentation Update');
+  lines.push('## Redpanda Connect Documentation Update');
   lines.push('');
   lines.push(`**OSS Version:** ${diffData.comparison.oldVersion} → ${diffData.comparison.newVersion}`);
 
@@ -383,7 +566,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   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');
+    lines.push('**No changes detected** - Documentation is up to date');
     lines.push('');
     lines.push('<!-- PR_SUMMARY_END -->');
     return lines.join('\n');
@@ -418,11 +601,11 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   }
 
   if (stats.removedComponents > 0) {
-    lines.push(`- **${stats.removedComponents}** removed connector${stats.removedComponents !== 1 ? 's' : ''} ⚠️`);
+    lines.push(`- **${stats.removedComponents}** removed connector${stats.removedComponents !== 1 ? 's' : ''}`);
   }
 
   if (stats.removedFields > 0) {
-    lines.push(`- **${stats.removedFields}** removed field${stats.removedFields !== 1 ? 's' : ''} ⚠️`);
+    lines.push(`- **${stats.removedFields}** removed field${stats.removedFields !== 1 ? 's' : ''}`);
   }
 
   if (stats.deprecatedComponents > 0) {
@@ -433,15 +616,39 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
     lines.push(`- **${stats.deprecatedFields}** deprecated field${stats.deprecatedFields !== 1 ? 's' : ''}`);
   }
 
+  if (stats.newBloblangMethods > 0) {
+    lines.push(`- **${stats.newBloblangMethods}** new Bloblang method${stats.newBloblangMethods !== 1 ? 's' : ''}`);
+  }
+
+  if (stats.newBloblangFunctions > 0) {
+    lines.push(`- **${stats.newBloblangFunctions}** new Bloblang function${stats.newBloblangFunctions !== 1 ? 's' : ''}`);
+  }
+
+  if (stats.removedBloblangMethods > 0) {
+    lines.push(`- **${stats.removedBloblangMethods}** removed Bloblang method${stats.removedBloblangMethods !== 1 ? 's' : ''}`);
+  }
+
+  if (stats.removedBloblangFunctions > 0) {
+    lines.push(`- **${stats.removedBloblangFunctions}** removed Bloblang function${stats.removedBloblangFunctions !== 1 ? 's' : ''}`);
+  }
+
+  if (stats.deprecatedBloblangMethods > 0) {
+    lines.push(`- **${stats.deprecatedBloblangMethods}** deprecated Bloblang method${stats.deprecatedBloblangMethods !== 1 ? 's' : ''}`);
+  }
+
+  if (stats.deprecatedBloblangFunctions > 0) {
+    lines.push(`- **${stats.deprecatedBloblangFunctions}** deprecated Bloblang function${stats.deprecatedBloblangFunctions !== 1 ? 's' : ''}`);
+  }
+
   if (stats.changedDefaults > 0) {
-    lines.push(`- **${stats.changedDefaults}** default value change${stats.changedDefaults !== 1 ? 's' : ''} ⚠️`);
+    lines.push(`- **${stats.changedDefaults}** default value change${stats.changedDefaults !== 1 ? 's' : ''}`);
   }
 
   lines.push('');
 
   // Writer Reminder for Commercial Names
   if (stats.newComponents > 0) {
-    lines.push('### ✍️ Writer Action Required');
+    lines.push('### Writer Action Required');
     lines.push('');
     lines.push('For each new connector, add the `:page-commercial-names:` attribute to the frontmatter:');
     lines.push('');
@@ -524,7 +731,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   if (stats.changedDefaults > 0) breakingChanges.push('changed defaults');
 
   if (breakingChanges.length > 0) {
-    lines.push('### ⚠️ Breaking Changes Detected');
+    lines.push('### Breaking Changes Detected');
     lines.push('');
     lines.push(`This update includes **${breakingChanges.join(', ')}** that may affect existing configurations.`);
     lines.push('');
@@ -598,7 +805,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   }
 
   if (missingDescriptions.length > 0) {
-    lines.push('### ⚠️ Missing Descriptions');
+    lines.push('### Missing Descriptions');
     lines.push('');
     lines.push(`**${missingDescriptions.length}** item${missingDescriptions.length !== 1 ? 's' : ''} missing descriptions - these need writer attention:`);
     lines.push('');
@@ -643,7 +850,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   if (missingDescriptions.length > 0) {
     actionItems.push({
       priority: 0,
-      text: `⚠️ Add descriptions for ${missingDescriptions.length} component${missingDescriptions.length !== 1 ? 's' : ''}/field${missingDescriptions.length !== 1 ? 's' : ''} (see Missing Descriptions section)`
+      text: `Add descriptions for ${missingDescriptions.length} component${missingDescriptions.length !== 1 ? 's' : ''}/field${missingDescriptions.length !== 1 ? 's' : ''} (see Missing Descriptions section)`
     });
   }
 
@@ -721,9 +928,20 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   lines.push('');
 
+  // Bloblang methods and functions
+  const bloblangLines = renderBloblangChanges({
+    newMethods: diffData.details.newBloblangMethods || [],
+    newFunctions: diffData.details.newBloblangFunctions || [],
+    removedMethods: diffData.details.removedBloblangMethods || [],
+    removedFunctions: diffData.details.removedBloblangFunctions || [],
+    deprecatedMethods: diffData.details.deprecatedBloblangMethods || [],
+    deprecatedFunctions: diffData.details.deprecatedBloblangFunctions || []
+  }, false); // includeVersion = false for single-version summaries
+  lines.push(...bloblangLines);
+
   // Detailed breakdown (expandable)
   lines.push('<details>');
-  lines.push('<summary><strong>📋 Detailed Changes</strong> (click to expand)</summary>');
+  lines.push('<summary><strong>Detailed Changes</strong> (click to expand)</summary>');
   lines.push('');
 
   // New Connectors
@@ -861,7 +1079,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   // Removed Connectors
   if (stats.removedComponents > 0) {
-    lines.push('#### ⚠️ Removed Connectors');
+    lines.push('#### Removed Connectors');
     lines.push('');
     diffData.details.removedComponents.forEach(c => {
       lines.push(`- **${c.name}** (${c.type})`);
@@ -871,7 +1089,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   // Removed Fields
   if (stats.removedFields > 0) {
-    lines.push('#### ⚠️ Removed Fields');
+    lines.push('#### Removed Fields');
     lines.push('');
 
     const fieldsByComponent = {};
@@ -927,7 +1145,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   // Changed Defaults
   if (stats.changedDefaults > 0) {
-    lines.push('#### ⚠️ Changed Default Values');
+    lines.push('#### Changed Default Values');
     lines.push('');
 
     const changesByComponent = {};
@@ -950,6 +1168,66 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
     });
   }
 
+  // New Bloblang Methods
+  if (stats.newBloblangMethods > 0 && diffData.details.newBloblangMethods) {
+    lines.push('#### New Bloblang Methods');
+    lines.push('');
+    diffData.details.newBloblangMethods.forEach(methodName => {
+      lines.push(`- \`${methodName}\``);
+    });
+    lines.push('');
+  }
+
+  // New Bloblang Functions
+  if (stats.newBloblangFunctions > 0 && diffData.details.newBloblangFunctions) {
+    lines.push('#### New Bloblang Functions');
+    lines.push('');
+    diffData.details.newBloblangFunctions.forEach(funcName => {
+      lines.push(`- \`${funcName}\``);
+    });
+    lines.push('');
+  }
+
+  // Removed Bloblang Methods
+  if (stats.removedBloblangMethods > 0 && diffData.details.removedBloblangMethods) {
+    lines.push('#### Removed Bloblang Methods');
+    lines.push('');
+    diffData.details.removedBloblangMethods.forEach(methodName => {
+      lines.push(`- \`${methodName}\``);
+    });
+    lines.push('');
+  }
+
+  // Removed Bloblang Functions
+  if (stats.removedBloblangFunctions > 0 && diffData.details.removedBloblangFunctions) {
+    lines.push('#### Removed Bloblang Functions');
+    lines.push('');
+    diffData.details.removedBloblangFunctions.forEach(funcName => {
+      lines.push(`- \`${funcName}\``);
+    });
+    lines.push('');
+  }
+
+  // Deprecated Bloblang Methods
+  if (stats.deprecatedBloblangMethods > 0 && diffData.details.deprecatedBloblangMethods) {
+    lines.push('#### Deprecated Bloblang Methods');
+    lines.push('');
+    diffData.details.deprecatedBloblangMethods.forEach(methodName => {
+      lines.push(`- \`${methodName}\``);
+    });
+    lines.push('');
+  }
+
+  // Deprecated Bloblang Functions
+  if (stats.deprecatedBloblangFunctions > 0 && diffData.details.deprecatedBloblangFunctions) {
+    lines.push('#### Deprecated Bloblang Functions');
+    lines.push('');
+    diffData.details.deprecatedBloblangFunctions.forEach(funcName => {
+      lines.push(`- \`${funcName}\``);
+    });
+    lines.push('');
+  }
+
   // Cloud Support Gap Analysis
   if (binaryAnalysis && binaryAnalysis.comparison.notInCloud.length > 0) {
     lines.push('#### 🔍 Cloud Support Gap Analysis');

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

@@ -163,6 +163,50 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
     });
   });
 
+  // Detect new/removed Bloblang methods and functions
+  const oldMethods = new Set((oldIndex['bloblang-methods'] || []).filter(Boolean).map(m => m.name).filter(Boolean));
+  const newMethods = new Set((newIndex['bloblang-methods'] || []).filter(Boolean).map(m => m.name).filter(Boolean));
+  const oldFunctions = new Set((oldIndex['bloblang-functions'] || []).filter(Boolean).map(f => f.name).filter(Boolean));
+  const newFunctions = new Set((newIndex['bloblang-functions'] || []).filter(Boolean).map(f => f.name).filter(Boolean));
+
+  const newBloblangMethods = Array.from(newMethods).filter(m => !oldMethods.has(m)).sort();
+  const removedBloblangMethods = Array.from(oldMethods).filter(m => !newMethods.has(m)).sort();
+  const newBloblangFunctions = Array.from(newFunctions).filter(f => !oldFunctions.has(f)).sort();
+  const removedBloblangFunctions = Array.from(oldFunctions).filter(f => !newFunctions.has(f)).sort();
+
+  // Detect deprecated Bloblang methods and functions
+  const deprecatedBloblangMethods = [];
+  const deprecatedBloblangFunctions = [];
+
+  const oldMethodsMap = new Map((oldIndex['bloblang-methods'] || []).filter(Boolean).filter(m => m.name).map(m => [m.name, m]));
+  const newMethodsMap = new Map((newIndex['bloblang-methods'] || []).filter(Boolean).filter(m => m.name).map(m => [m.name, m]));
+  const oldFunctionsMap = new Map((oldIndex['bloblang-functions'] || []).filter(Boolean).filter(f => f.name).map(f => [f.name, f]));
+  const newFunctionsMap = new Map((newIndex['bloblang-functions'] || []).filter(Boolean).filter(f => f.name).map(f => [f.name, f]));
+
+  // Check methods for newly deprecated status
+  newMethodsMap.forEach((newMethod, name) => {
+    const oldMethod = oldMethodsMap.get(name);
+    if (oldMethod) {
+      const oldStatus = (oldMethod.status || '').toLowerCase();
+      const newStatus = (newMethod.status || '').toLowerCase();
+      if (oldStatus !== 'deprecated' && newStatus === 'deprecated') {
+        deprecatedBloblangMethods.push(name);
+      }
+    }
+  });
+
+  // Check functions for newly deprecated status
+  newFunctionsMap.forEach((newFunction, name) => {
+    const oldFunction = oldFunctionsMap.get(name);
+    if (oldFunction) {
+      const oldStatus = (oldFunction.status || '').toLowerCase();
+      const newStatus = (newFunction.status || '').toLowerCase();
+      if (oldStatus !== 'deprecated' && newStatus === 'deprecated') {
+        deprecatedBloblangFunctions.push(name);
+      }
+    }
+  });
+
   const result = {
     comparison: {
       oldVersion: opts.oldVersion || '',
@@ -176,7 +220,13 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       removedFields: removedFields.length,
       deprecatedComponents: deprecatedComponents.length,
       deprecatedFields: deprecatedFields.length,
-      changedDefaults: changedDefaults.length
+      changedDefaults: changedDefaults.length,
+      newBloblangMethods: newBloblangMethods.length,
+      removedBloblangMethods: removedBloblangMethods.length,
+      newBloblangFunctions: newBloblangFunctions.length,
+      removedBloblangFunctions: removedBloblangFunctions.length,
+      deprecatedBloblangMethods: deprecatedBloblangMethods.length,
+      deprecatedBloblangFunctions: deprecatedBloblangFunctions.length
     },
     details: {
       newComponents,
@@ -185,7 +235,13 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
       removedFields,
       deprecatedComponents,
       deprecatedFields,
-      changedDefaults
+      changedDefaults,
+      newBloblangMethods,
+      removedBloblangMethods,
+      newBloblangFunctions,
+      removedBloblangFunctions,
+      deprecatedBloblangMethods,
+      deprecatedBloblangFunctions
     }
   };
 

package/tools/redpanda-connect/templates/bloblang-function.hbs

@@ -1,15 +1,41 @@
 // This content is autogenerated. Do not edit manually. To override descriptions, use the doc-tools CLI with the --overrides option: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1247543314/Generate+reference+docs+for+Redpanda+Connect
 
 = {{name}}
-
 {{#if signature}}
+
 *Signature*: `{{signature}}`
 {{/if}}
+{{#if (eq status "deprecated")}}
 
+[WARNING]
+====
+This {{#if signature}}function{{else}}method{{/if}} is deprecated and will be removed in a future version.
+====
+{{/if}}
 {{#if description}}
-{{description}}
+
+{{{ensurePeriod description}}}
 {{/if}}
 
+{{#if params}}
+{{#if params.named}}
+
+== Parameters
+
+[cols="1,1,3"]
+|===
+| Name | Type | Description
+
+{{#each params.named}}
+| `{{name}}`{{#if is_optional}} (optional){{/if}}
+| `{{type}}`
+| {{{description}}}
+
+{{/each}}
+|===
+
+{{/if}}
+{{/if}}
 
 {{#if examples}}
 == Examples

package/tools/redpanda-connect/templates/bloblang-functions-overview.hbs

@@ -0,0 +1,29 @@
+= Bloblang Functions
+// tag::single-source[]
+:description: A list of Bloblang functions
+
+// © 2024 Redpanda Data Inc.
+
+
+Functions can be placed anywhere and allow you to extract information from your environment, generate values, or access data from the underlying message being mapped:
+
+```bloblang
+root.doc.id = uuid_v4()
+root.doc.received_at = now()
+root.doc.host = hostname()
+```
+
+Functions support both named and nameless style arguments:
+
+```bloblang
+root.values_one = range(start: 0, stop: this.max, step: 2)
+root.values_two = range(0, this.max, 2)
+
+# In:  {"max":10}
+```
+{{#each functions}}
+
+include::redpanda-connect:components:partial$bloblang-functions/{{this}}.adoc[leveloffset=+1]
+{{/each}}
+
+// end::single-source[]

package/tools/redpanda-connect/templates/bloblang-methods-overview.hbs

@@ -0,0 +1,39 @@
+= Bloblang Methods
+// tag::single-source[]
+:description: A list of Bloblang methods
+
+// © 2024 Redpanda Data Inc.
+
+
+Methods provide most of the power in Bloblang as they allow you to augment values and can be added to any expression (including other methods):
+
+```bloblang
+root.doc.id = this.thing.id.string().catch(uuid_v4())
+root.doc.reduced_nums = this.thing.nums.map_each(num -> if num < 10 {
+  deleted()
+} else {
+  num - 10
+})
+root.has_good_taste = ["pikachu","mewtwo","magmar"].contains(this.user.fav_pokemon)
+
+# In:  {"thing":{"id":123,"nums":[5,12,18,7,25]},"user":{"fav_pokemon":"pikachu"}}
+```
+
+Methods support both named and nameless style arguments:
+
+```bloblang
+root.foo_one = this.(bar | baz).trim().replace_all(old: "dog", new: "cat")
+root.foo_two = this.(bar | baz).trim().replace_all("dog", "cat")
+
+# In:  {"bar":"  I love my dog  "}
+```
+{{#each categories}}
+
+== {{{toSentenceCase this.name}}}
+{{#each this.methods}}
+
+include::redpanda-connect:components:partial$bloblang-methods/{{this}}.adoc[leveloffset=+2]
+{{/each}}
+{{/each}}
+
+// end::single-source[]

package/tools/redpanda-connect/templates/connector.hbs

@@ -1,10 +1,9 @@
 = {{{name}}}
 // tag::single-source[]
 :type: {{type}}
-:status: {{status}}
 {{#if support}}:support: {{support}}{{/if}}
 :categories: [{{join categories ", "}}]
-:description: {{#if summary}}{{{summary}}}{{else if description}}{{description}}{{else}}TODO: Missing description. Add a description in the overrides file or source data.{{/if}}
+:description: {{#if summary}}{{{summary}}}{{else if description}}{{description}}{{else}}// TODO: Missing description. Add a description in the overrides file or source data.{{/if}}
 
 component_type_dropdown::[]
 

package/tools/redpanda-connect/templates/intro.hbs

@@ -9,5 +9,5 @@ endif::[]
 {{#if description}}
 {{{description}}}
 {{else}}
-TODO: Missing description. Add a description in the overrides file or source data.
+// TODO: Missing description. Add a description in the overrides file or source data.
 {{/if}}