@redpanda-data/docs-extensions-and-macros 3.9.0 → 3.10.0

package/README.adoc

@@ -46,6 +46,96 @@ This section documents the Antora extensions provided by this library and how to
 
 IMPORTANT: Ensure you register each extension under the `antora.extensions` key in the playbook, not the `asciidoc.extensions` key.
 
+=== Add Bloblang samples to pages
+
+The `collect-bloblang-samples` extension processes Bloblang examples from YAML files in the `examples` directory of the `redpanda-connect` component. This extension ensures that these examples are accessible as structured data for use in UI components or documentation, such as sample dropdowns in a Bloblang playground.
+
+It validates, sorts, and attaches the processed examples as a JSON object to the Antora page attributes. The extension ensures examples have unique titles, mandatory fields (`input` and `mapping`), and are sorted in alphabetical order.
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options
+
+To enable the extension, add it to your Antora playbook under the `antora.extensions` key. No additional configuration is required.
+
+[,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/collect-bloblang-samples'
+----
+
+==== Example Bloblang YAML file
+
+The following YAML file is an example of how to define a Bloblang sample:
+
+[,yaml]
+----
+title: Hello world
+input: |
+  {
+    "message": "hello world"
+  }
+mapping: |
+  root.message = this.message.uppercase()
+----
+
+==== Sample output
+
+The processed examples are added as JSON to the `page-bloblang-samples` attribute. For example:
+
+[,json]
+----
+{
+  "hello-world.yaml": {
+    "title": "Hello world",
+    "input": "{\n  \"message\": \"hello world\"\n}\n",
+    "mapping": "root.message = this.message.uppercase()\n"
+  },
+  "array-processing.yaml": {
+    "title": "Array processing",
+    "input": "{\n  \"numbers\": [1, 2, 3, 4, 5]\n}\n",
+    "mapping": "root.even_numbers = this.numbers.filter(n -> n % 2 == 0)"
+  }
+}
+----
+
+=== Add pages to root
+
+The `add-pages-to-root` extension allows you to copy files from your Antora content catalog to the root of the site during the build process. This is particularly useful for files like `llms.txt` or any custom files that need to be directly accessible at the site's root level.
+
+This extension processes a list of file paths provided in the playbook configuration, locates those files in the Antora content catalog, and adds them to the site's root directory during the publishing phase. Each file's content and basename are preserved in the process.
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options
+
+Add the `add-pages-to-root` extension to your Antora playbook under the `antora.extensions` key, and specify the list of files to process in the `files` configuration.
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-pages-to-root'
+      files:
+        - home:ROOT:attachment$custom-file.txt
+----
+
+==== Registration example
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/add-pages-to-root'
+      files:
+        - home:ROOT:attachment$custom-file.txt
+----
+
 === Algolia indexer
 
 This extension generates an Algolia index for each version of each component. The index entries are then saved to Algolia using the `saveObjects()` method, and also saved as JSON files in the site catalog. JSON files are published to the site root using the template `algolia-<component>-<version>.json`.

package/extensions/add-global-attributes.js

@@ -13,7 +13,6 @@ const ATTRIBUTES_PATH = 'modules/ROOT/partials/';  // Default path within the 's
 
 module.exports.register = function ({ config }) {
   const logger = this.getLogger('global-attributes-extension');
-  const chalk = require('chalk');
 
   /**
    * Load global attributes from a specified local file if provided.
@@ -30,7 +29,7 @@ module.exports.register = function ({ config }) {
       const fileAttributes = yaml.load(fileContents);
 
       siteCatalog.attributeFile = _.merge({}, fileAttributes);
-      console.log(chalk.green(`Loaded global attributes from local file "${localAttributesFile}".`));
+      logger.info(`Loaded global attributes from local file "${localAttributesFile}".`);
       return true;  // Return true if the local attributes were successfully loaded
 
     } catch (error) {
@@ -64,7 +63,7 @@ module.exports.register = function ({ config }) {
                 const fileAttributes = yaml.load(file.contents.toString('utf8'));
                 return _.merge(acc, fileAttributes);
               }, {});
-              console.log(chalk.green('Loaded global attributes from shared component.'));
+              logger.info('Loaded global attributes from shared component.');
             }
             break;
           }

package/extensions/add-pages-to-root.js

@@ -0,0 +1,30 @@
+module.exports.register = function ({ config }) {
+  this.on('beforePublish', ({ siteCatalog, contentCatalog }) => {
+    const logger = this.getLogger('add-pages-to-site-root');
+    if (!config || !config.files || !config.files.length) {
+      logger.debug('No files configured to be added to the root directory.');
+      return;
+    }
+
+    logger.debug('Files to process:', config.files);
+
+    config.files.forEach(filePath => {
+      const resource = contentCatalog.resolveResource(filePath);
+      if (resource) {
+        const basename = resource.src.basename; // Get the file's basename
+        const contentsBuffer = resource.contents; // Access the file's contents as a Buffer
+        logger.debug(`Processing file: ${basename}`);
+        // Add the file to the root directory in the site catalog
+        siteCatalog.addFile({
+          contents: contentsBuffer,
+          out: {
+            path: basename, // Add the file to the root directory
+          },
+        });
+        delete resource.out
+      } else {
+        logger.warn(`File not resolved: ${filePath}`);
+      }
+    });
+  });
+};

package/extensions/aggregate-terms.js

@@ -11,7 +11,6 @@ const TERMS_PATH = 'modules/terms/partials/';  // Default path within the 'share
 
 module.exports.register = function ({ config }) {
   const logger = this.getLogger('term-aggregation-extension');
-  const chalk = require('chalk');
 
   /**
    * Function to process term content, extracting hover text and links.
@@ -67,7 +66,7 @@ module.exports.register = function ({ config }) {
         siteCatalog.termsByCategory[formattedCategory].push({ name: file, content: termContent });
       });
 
-      console.log(chalk.green(`Categorized terms from local terms path "${termsPath}".`));
+      logger.info(`Categorized terms from local terms path "${termsPath}".`);
       return true;
 
     } catch (error) {
@@ -109,7 +108,7 @@ module.exports.register = function ({ config }) {
               siteCatalog.termsByCategory[formattedCategory].push({ name: file.basename, content: termContent });
             });
 
-            console.log(chalk.green('Categorized terms from shared component.'));
+            logger.info('Categorized terms from shared component.');
             break;
           }
         }
@@ -150,7 +149,7 @@ module.exports.register = function ({ config }) {
             });
 
             glossaryPage.contents = Buffer.from(glossaryContent, 'utf8');
-            console.log(chalk.green(`Merged terms into glossary for ${component} component${version ? ' version ' + version : ''}.`));
+            logger.info(`Merged terms into glossary for ${component} component${version ? ' version ' + version : ''}.`);
           } else {
             logger.info(`Skipping ${title} ${version ? ' version ' + version : ''} - No glossary page (reference:glossary.adoc) found`);
           }

package/extensions/algolia-indexer/generate-index.js

@@ -104,7 +104,7 @@ function generateIndex (playbook, contentCatalog, { indexLatestOnly = false, exc
     // Start handling the article content
     const article = root.querySelector('article.doc')
     if (!article) {
-      logger.info(`Page is not an article...skipping ${page.pub.url}`)
+      logger.warn(`Page is not an article...skipping ${page.pub.url}`)
       continue
     }
 

package/extensions/algolia-indexer/index.js

@@ -1,12 +1,9 @@
 'use strict'
 
 const generateIndex = require('./generate-index')
-const chalk = require('chalk')
 const algoliasearch = require('algoliasearch')
 const http = require('http')
 const https = require('https')
-const fs = require('fs')
-const path = require('path')
 const _ = require('lodash')
 process.env.UV_THREADPOOL_SIZE=16
 
@@ -106,7 +103,7 @@ function register({
         // Upload new records only if the objects have been updated or they are new.
         // See https://www.algolia.com/doc/api-reference/api-methods/batch/?client=javascript
         await client.multipleBatch(batchActions).then(() => {
-          console.log('Batch operations completed successfully');
+          logger.info('Batch operations completed successfully');
         }).catch(error => {
           logger.error(`Error uploading records to Algolia: ${error.message}`);
         });
@@ -127,10 +124,10 @@ function register({
       });
     }
 
-    console.log(chalk.green('Updated records:' + totalObjectsToUpdate))
-    console.log(chalk.green('New records:' + totalObjectsToAdd))
+    logger.info('Updated records:' + totalObjectsToUpdate)
+    logger.info('New records:' + totalObjectsToAdd)
 
-    totalObjectsToAdd === 0 && totalObjectsToUpdate === 0 && console.log(chalk.green('No new records uploaded or existing records updated'))
+    totalObjectsToAdd === 0 && totalObjectsToUpdate === 0 && logger.info('No new records uploaded or existing records updated')
   })
 
   process.on('exit', () => {

package/extensions/collect-bloblang-samples.js

@@ -0,0 +1,78 @@
+const yaml = require('js-yaml');
+
+module.exports.register = function () {
+  const logger = this.getLogger('collect-bloblang-samples');
+
+  this.on('contentClassified', ({ contentCatalog }) => {
+    const collectExamples = (examples, componentName) => {
+      const bloblangSamples = [];
+      const seenTitles = new Set();
+
+      examples
+        .filter((example) => example.src.relative.startsWith('playground/')) // Only include files in the 'bloblang' subdirectory
+        .forEach((example) => {
+          try {
+            const content = example.contents.toString('utf8');
+            const parsedContent = yaml.load(content);
+
+            if (!parsedContent.title) {
+              logger.warn(`Skipping example '${example.src.basename}' in '${componentName}': Missing title.`);
+              return;
+            }
+
+            if (seenTitles.has(parsedContent.title)) {
+              logger.warn(
+                `Duplicate title found: '${parsedContent.title}' in '${example.src.basename}' (${componentName}). Skipping.`
+              );
+              return;
+            }
+
+            if (!parsedContent.input || !parsedContent.mapping) {
+              logger.warn(
+                `Skipping example '${example.src.basename}' in '${componentName}': Missing input or mapping.`
+              );
+              return;
+            }
+
+            logger.info(`Loaded example: ${example.src.basename} with title: '${parsedContent.title}'`);
+            seenTitles.add(parsedContent.title);
+
+            bloblangSamples.push({ filename: example.src.basename, ...parsedContent });
+          } catch (error) {
+            logger.error(`Error processing example '${example.src.basename}' in '${componentName}':`, error);
+          }
+        });
+
+      bloblangSamples.sort((a, b) => a.title.localeCompare(b.title));
+
+      return bloblangSamples.reduce((acc, sample) => {
+        acc[sample.filename] = sample;
+        return acc;
+      }, {});
+    };
+
+    // Fetch examples from both components
+    const examples = contentCatalog.findBy({ component: 'redpanda-connect', family: 'example' });
+    const previewExamples = contentCatalog.findBy({ component: 'preview', family: 'example' });
+
+    if (!examples.length) logger.warn(`No examples found in the 'redpanda-connect' component.`);
+
+    // Get components
+    const connect = contentCatalog.getComponents().find((c) => c.name === 'redpanda-connect');
+    const preview = contentCatalog.getComponents().find((c) => c.name === 'preview');
+
+    if (connect) {
+      const connectSamples = collectExamples(examples, 'redpanda-connect');
+      connect.latest.asciidoc.attributes['page-bloblang-samples'] = JSON.stringify(connectSamples);
+      logger.debug(`Bloblang samples added to 'redpanda-connect': ${JSON.stringify(connectSamples, null, 2)}`);
+    } else {
+      logger.warn(`Component 'redpanda-connect' not found.`);
+    }
+
+    if (preview) {
+      const previewSamples = collectExamples(previewExamples, 'preview');
+      preview.latest.asciidoc.attributes['page-bloblang-samples'] = JSON.stringify(previewSamples);
+      logger.debug(`Bloblang samples added to 'preview': ${JSON.stringify(previewSamples, null, 2)}`);
+    }
+  });
+};

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

@@ -116,7 +116,7 @@ module.exports.register = function ({ config }) {
       redpandaConnect.latest.asciidoc.attributes.driverSupportData = driverSupportData
       redpandaConnect.latest.asciidoc.attributes.cacheSupportData = cacheSupportData
 
-      logger.info(`Added Redpanda Connect data to latest Asciidoc object.`)
+      logger.debug(`Added Redpanda Connect data to latest Asciidoc object.`)
       logger.debug(`${JSON.stringify({ connectCategoriesData, flatComponentsData }, null, 2)}`)
     } catch (error) {
       logger.error(`Error processing Redpanda Connect files: ${error.message}`)

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

@@ -141,7 +141,7 @@ module.exports.register = function ({ config }) {
 
       // Log a warning if neither URL was found (only warn for missing cloud if it should support cloud)
       if (!redpandaConnectUrl && (!redpandaCloudUrl && is_cloud_supported === 'y')) {
-        logger.info(`Docs missing for: ${connector} of type: ${type}`);
+        logger.warn(`Docs missing for: ${connector} of type: ${type}`);
       }
 
       // Return the translated and enriched row

package/extensions/validate-attributes.js

@@ -34,7 +34,7 @@ function processEnvironmentAttributes(page, logger) {
       // If the env attribute exists, set a corresponding page- attribute for use in the UI
       const pageEnvAttr = `page-${envAttr}`;
       page.asciidoc.attributes[pageEnvAttr] = true;
-      logger.info(`Set '${pageEnvAttr}' for ${page.asciidoc.attributes['page-relative-src-path']}`);
+      logger.debug(`Set '${pageEnvAttr}' for ${page.asciidoc.attributes['page-relative-src-path']}`);
     }
   });
 }
@@ -53,7 +53,7 @@ function validateCategories(pageCategoryList, pageInfo, categoryMap, logger) {
       if (!adjustedCategories.has(parentCategory)) {
         // Add the parent category since it's missing
         adjustedCategories.add(parentCategory);
-        logger.info(`Added missing parent category '${parentCategory}' for subcategory '${category}' in ${pageInfo}`);
+        logger.debug(`Added missing parent category '${parentCategory}' for subcategory '${category}' in ${pageInfo}`);
       }
     }
     // Check if the current category is not a valid category or subcategory

package/extensions/version-fetcher/set-latest-version.js

@@ -6,7 +6,6 @@ module.exports.register = function ({ config }) {
   const GetLatestOperatorVersion = require('./get-latest-operator-version');
   const GetLatestHelmChartVersion = require('./get-latest-redpanda-helm-version');
   const GetLatestConnectVersion = require('./get-latest-connect');
-  const chalk = require('chalk');
   const logger = this.getLogger('set-latest-version-extension');
 
   if (!process.env.REDPANDA_GITHUB_TOKEN) {
@@ -96,7 +95,7 @@ module.exports.register = function ({ config }) {
         }
       });
 
-      console.log(chalk.green('Updated Redpanda documentation versions successfully.'));
+      logger.info('Updated Redpanda documentation versions successfully.');
       logger.info(`Latest Redpanda version: ${latestVersions.redpanda.latestRedpandaRelease.version}`);
       if (latestVersions.redpanda.latestRCRelease) logger.info(`Latest Redpanda beta version: ${latestVersions.redpanda.latestRCRelease.version}`);
       logger.info(`Latest Connect version: ${latestVersions.connect}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -30,6 +30,8 @@
       "require": "./extensions/unlisted-pages.js"
     },
     "./extensions/replace-attributes-in-attachments": "./extensions/replace-attributes-in-attachments.js",
+    "./extensions/add-pages-to-root": "./extensions/add-pages-to-root.js",
+    "./extensions/collect-bloblang-samples": "./extensions/collect-bloblang-samples.js",
     "./extensions/generate-rp-connect-categories": "./extensions/generate-rp-connect-categories.js",
     "./extensions/generate-rp-connect-info": "./extensions/generate-rp-connect-info.js",
     "./extensions/add-global-attributes": "./extensions/add-global-attributes.js",