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

package/README.adoc

@@ -46,6 +46,40 @@ 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 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/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.9.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -30,6 +30,7 @@
       "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/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",