@redpanda-data/docs-extensions-and-macros 3.10.1 → 3.11.0

package/README.adoc

@@ -52,6 +52,24 @@ The `collect-bloblang-samples` extension processes Bloblang examples from YAML f
 
 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.
 
+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)"
+  }
+}
+----
+
 ==== Environment variables
 
 This extension does not require any environment variables.
@@ -82,26 +100,6 @@ 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.
@@ -183,7 +181,7 @@ This extension does not require any environment variables.
 
 There are no configurable options for this extension.
 
-==== Registration Example
+==== Registration example
 
 ```yaml
 antora:
@@ -191,6 +189,110 @@ antora:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories'
 ```
 
+=== Generate index data
+
+The `generate-index-data` extension creates structured index data about doc pages based on configurable filters. The indexed data is saved to a specified attribute in all component versions, enabling the dynamic generation of categorized links and descriptions within your docs using UI templates.
+
+This extension allows you to define multiple indexing criteria, such as component, URL filter, and environment type.
+
+The generated data is an array of objects, where each object represents a component version. Each object contains the following properties:
+
+- `component` (string):
+  The name of the Antora component.
+
+- `version` (string):
+  The version of the component.
+
+- `pages` (array):
+  A list of pages that match the indexing criteria. Each page contains:
+** `title` (string): The title of the doc page.
+** `url` (string): The URL of the doc page relative to the site root.
+** `description` (string): A brief description sourced from the `:description:` attribute in the AsciiDoc file. Defaults to an empty string if not provided.
+
+Example:
+
+```json
+[
+  {
+    "component": "ROOT",
+    "version": "24.3",
+    "pages": [
+      {
+        "title": "Manage Debug Bundles in Redpanda Console",
+        "url": "/current/console/ui/generate-bundle/",
+        "description": "Learn how to generate, download, and delete debug bundles in Redpanda Console for comprehensive cluster diagnostics."
+      },
+    ]
+  }
+]
+```
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options
+
+The extension accepts the following options in the Antora playbook.
+
+NOTE: Ensure filters are well-defined to minimize unnecessary processing. Avoid overly broad configurations in `data.sets`.
+
+- `data.sets` (required): An object defining one or more indexing configurations. Each configuration (or set) accepts the following options:
+
+** `component` (string, required): The Antora component to search for pages.
+
+** `attribute_name` (string, required): The attribute name to assign the generated index data. This allows pages and templates to reference the index.
+
+** `filter` (string, optional): A substring to match within page URLs.
+
+** `env_type` (string, optional): Matches pages with environment-specific attributes (e.g., Docker, Kubernetes).
+
+** `output_file` (string, optional): Save the generated index data as a JSON file at the specified path. If not provided, no file is created.
+
+==== Example configuration
+
+Here's an example configuration to enable the generate-index-data-extension:
+
+```yaml
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data-extension'
+      data:
+        sets:
+          console_ui:
+            component: ROOT  # Search the ROOT component
+            filter: console/ui # Filter pages containing this substring in their URL
+            attribute_name: console-ui-index # Save the result in this attribute
+            output_file: redpanda-labs/console-ui-index.json # Save data to this file
+          docker_labs:
+            component: redpanda-labs
+            filter: docker-compose
+            env_type: Docker
+            attribute_name: docker-labs-index
+```
+
+==== Use the generated data
+
+The index data can be referenced in AsciiDoc pages by specifying the following required attributes:
+
+```asciidoc
+= CONSOLE UI
+:page-index-data: console-ui-index <1>
+:page-role: index-list <2>
+```
+
+<1> The attribute whose data you want to display on the page. This must match an attribute configured in the extension.
+<2> The page role. This role specfies the UI template that renders the data in the `page-index-data` on the page.
+
+You can optionally display pages only if they match the component and version of the current Asciidoc page by adding the `:page-match-component-version:` attribute.
+
+```asciidoc
+= CONSOLE UI
+:page-index-data: console-ui-index
+:page-role: index-list
+:page-match-component-version: ''
+```
+
 === Redpanda Connect tag modifier
 
 This extension updates the playbook to use the latest release tag for the Redpanda Connect documentation. It ensures that the Redpanda Connect documentation is always pulled from the latest release tag available on GitHub.

package/extensions/generate-index-data.js

@@ -0,0 +1,193 @@
+'use strict';
+const _ = require('lodash');
+
+module.exports.register = function ({ config }) {
+  const logger = this.getLogger('generate-index-data-extension');
+
+  this.on('documentsConverted', async ({ contentCatalog, siteCatalog }) => {
+    // Ensure data.sets exists and is an object
+    const setsConfig = _.get(config, 'data.sets', {});
+    if (!setsConfig || Object.keys(setsConfig).length === 0) {
+      logger.info('No index sets defined in the configuration. Skipping index data generation.');
+      return;
+    }
+
+    try {
+      // Process each defined index set
+      for (const [setName, setParams] of Object.entries(setsConfig)) {
+        logger.info(`Processing index set: ${setName}`);
+        const { component, filter, env_type, output_file, attribute_name } = setParams;
+
+        // Validate required parameters
+        const requiredParams = ['component', 'attribute_name'];
+
+        const missingParams = requiredParams.filter(param => !setParams[param]);
+
+        if (missingParams.length > 0) {
+          logger.warn(`One or more required parameters are missing: ${missingParams.join(', ')} for set "${setName}". Skipping.`);
+          continue;
+        }
+
+        // Gather items based on the target version
+        const items = gatherItems(contentCatalog, {
+          component,
+          filter,
+          env_type,
+        }, logger);
+
+        if (!items.length) {
+          continue;
+        }
+
+        const uniqueItems = deduplicateAndSortItems(items);
+        await addDataAttributeToComponents(uniqueItems, contentCatalog, attribute_name, logger);
+        if (output_file) createIndexFile(uniqueItems, siteCatalog, output_file, logger);
+      }
+    } catch (error) {
+      logger.error(`Failed to generate indexes: ${error.stack}`);
+    }
+  });
+};
+
+/**
+ * Gathers items (pages) from the contentCatalog based on the provided setParams.
+ * setParams should contain:
+ *   - component (string, required): Component name to search
+ *   - filter (string, optional): A substring to match in the URL or other criteria
+ *   - env_type (string, optional): Deployment type to match ('Docker', 'Kubernetes', 'Linux', 'Redpanda Cloud')
+ */
+function gatherItems(contentCatalog, setParams, logger) {
+  const { component, filter, env_type } = setParams;
+
+  // Find the component in the catalog
+  const componentObj = contentCatalog.getComponents().find(comp => comp.name === component);
+  if (!componentObj) {
+    logger.warn(`Component "${component}" not found in the content catalog.`);
+    return [];
+  }
+
+  const result = [];
+
+  // Iterate through all versions of the component
+  componentObj.versions.forEach(versionObj => {
+    const versionPages = contentCatalog.findBy({ component, family: 'page', version: versionObj.version });
+
+    logger.debug(`Gathering pages for component "${component}" version "${versionObj.version}". Found ${versionPages.length} pages.`);
+
+    // Filter pages based on criteria
+    const matchedPages = versionPages.filter(page => {
+      const deploymentType = getDeploymentType(page.asciidoc.attributes);
+      const urlMatches = filter ? page.pub.url.includes(filter) : true;
+      const envMatches = env_type ? (deploymentType === env_type) : true;
+
+      return urlMatches && envMatches;
+    });
+
+    // Map matched pages to the desired structure
+    const pages = matchedPages.map(page => ({
+      title: page.asciidoc.doctitle,
+      url: page.pub.url,
+      description: page.asciidoc.attributes.description || ''
+    }));
+
+    // Add the component and version structure, even if pages is empty
+    result.push({
+      component,
+      version: versionObj.version,
+      pages
+    });
+
+    logger.debug(`Processed ${pages.length} pages for version "${versionObj.version}".`);
+  });
+
+  logger.debug(`Completed gathering items for component "${component}".`);
+  return result;
+}
+
+/**
+ * Deduplicates items by their URL and returns them in alphabetical order by title.
+ */
+function deduplicateAndSortItems(items) {
+  return items.map(item => {
+    const seenUrls = new Set();
+
+    // Deduplicate pages by URL
+    const deduplicatedPages = item.pages.filter(page => {
+      if (seenUrls.has(page.url)) {
+        return false;
+      }
+      seenUrls.add(page.url);
+      return true;
+    });
+
+    // Sort pages alphabetically by title
+    const sortedPages = deduplicatedPages.sort((a, b) => {
+      const titleA = a.title.toLowerCase();
+      const titleB = b.title.toLowerCase();
+      if (titleA < titleB) return -1;
+      if (titleA > titleB) return 1;
+      return 0;
+    });
+
+    return {
+      ...item,
+      pages: sortedPages
+    };
+  });
+}
+
+/**
+ * Add the gathered data as an attribute to all components.
+ *
+ * @param {Array} data - The deduplicated items to set as an attribute.
+ * @param {Object} contentCatalog - The content catalog from Antora.
+ * @param {string} attributeName - The name of the attribute to set.
+ * @param {Object} logger - The Antora logger.
+ */
+async function addDataAttributeToComponents(data, contentCatalog, attributeName, logger) {
+  try {
+    const jsonData = JSON.stringify(data, null, 2);
+    const components = await contentCatalog.getComponents();
+
+    components.forEach(component => {
+      component.versions.forEach(({ name, asciidoc }) => {
+        asciidoc.attributes[attributeName] = jsonData;
+        logger.debug(`Set attribute "${attributeName}" on component "${name}".`);
+      });
+    });
+
+    logger.info(`Added "${attributeName}" attribute to relevant component versions.`);
+  } catch (error) {
+    logger.error(`Failed to add data attribute "${attributeName}": ${error.message}`);
+  }
+}
+
+/**
+ * Create a JSON file in the output with the given data.
+ */
+function createIndexFile(data, siteCatalog, outputFile, logger) {
+  if (!outputFile) {
+    logger.info('No output_file specified, skipping JSON file creation.');
+    return;
+  }
+
+  const jsonData = JSON.stringify(data, null, 2);
+  siteCatalog.addFile({
+    contents: Buffer.from(jsonData, 'utf8'),
+    out: {
+      path: outputFile
+    },
+  });
+  logger.info(`Created "${outputFile}" with indexed data.`);
+}
+
+/**
+ * Determine the deployment type from AsciiDoc attributes.
+ */
+function getDeploymentType(attributes) {
+  return attributes['env-kubernetes'] ? 'Kubernetes'
+    : attributes['env-linux'] ? 'Linux'
+      : attributes['env-docker'] ? 'Docker'
+        : attributes['env-cloud'] ? 'Redpanda Cloud'
+          : attributes['page-cloud'] ? 'Redpanda Cloud' : '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.10.1",
+  "version": "3.11.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -33,6 +33,7 @@
     "./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-index-data": "./extensions/generate-index-data.js",
     "./extensions/generate-rp-connect-info": "./extensions/generate-rp-connect-info.js",
     "./extensions/add-global-attributes": "./extensions/add-global-attributes.js",
     "./extensions/version-fetcher/set-latest-version": "./extensions/version-fetcher/set-latest-version.js",