@redpanda-data/docs-extensions-and-macros 3.11.2 → 4.1.0

package/README.adoc

@@ -165,6 +165,71 @@ antora:
     index-latest-only: true
 ```
 
+=== Archive attachments
+
+The `archive-attachments` extension automates the packaging of specific attachment files into a compressed archive (`.tar.gz`) based on configurable patterns. This archive is then made available to the generated site, allowing users to easily download grouped resources such as Docker Compose configurations.
+
+This extension enables you to define which files and directories to include in the archive, ensuring that only relevant content is packaged and accessible.
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options
+
+The extension accepts the following options in the Antora playbook.
+
+Configure the extension in your Antora playbook by defining an array of archive configurations under `data.archives`. Each archive configuration includes:
+
+output_archive (string, required):: The name of the generated archive file.
+
+component (string, required):: The name of the Antora component whose attachments should be archived.
+
+file_patterns (array of strings, required):: Glob patterns specifying which attachment paths to include in the archive.
+
+NOTE: Ensure that `file_patterns` accurately reflect the paths of the attachments you want to archive. Overly broad patterns may include unintended files, while overly restrictive patterns might exclude necessary resources.
+
+==== Example configuration
+
+Here's an example configuration to enable the extension:
+
+```yaml
+antora:
+  extensions:
+    - require: '../docs-extensions-and-macros/extensions/archive-creation-extension.js'
+      data:
+        archives:
+          - output_archive: 'redpanda-quickstart.tar.gz' <1>
+            component: 'ROOT' <2>
+            file_patterns:
+              - '**/test-resources/**/docker-compose/**' <3>
+```
+
+<1> Defines the name of the generated archive placed at the site root.
+<2> Defines the name of the component in which to search for attachments.
+<3> Lists the glob patterns to match attachment paths for inclusion in the archive.
++
+- `**`: Matches any number of directories.
+- `/test-resources/`: Specifies that the matching should occur within the `test-resources/` directory.
+- `/docker-compose/`: Targets the `docker-compose/` directory and all its subdirectories.
+- `**:` Ensures that all files and nested directories within `docker-compose/` are included.
+
+=== Behavior with multiple components/versions
+
+*Scenario*: Multiple components and/or multiple versions of the same component contain attachments that match the defined file_patterns.
+
+*Outcome*: Separate archives for each component version.
+
+For each matching (component, version) pair, the extension creates a distinct archive named `<version>-<output_archive>`. For example:
+`24.3-redpanda-quickstart.tar.gz`.
+
+These archives are placed at the site root, ensuring they are easily accessible and do not overwrite each other.
+
+For the latest version of each component, the extension also adds the archive using the base `output_archive` name. As a result, the latest archives are accessible through a consistent filename, facilitating easy downloads without needing to reference version numbers.
+
+Because each archive has a unique filename based on the component version, there is no risk of archives overwriting each other.
+The only exception is the archive for the latest version, which consistently uses the `output_archive` name.
+
 === Component category aggregator
 
 This extension maps Redpanda Connect component data into a structured format:
@@ -189,6 +254,90 @@ antora:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories'
 ```
 
+=== Compute end-of-life extension
+
+This extension calculates and attaches metadata related to the end-of-life (EoL) status of docs pages, such as nearing EoL, past EoL, and associated EoL dates. This metadata can be used to display relevant banners or messages in docs to inform users about the lifecycle of each version.
+
+The extension leverages configuration settings provided in the Antora playbook to apply EoL calculations, specify the warning period, and include links to upgrade documentation and EoL policies.
+
+The extension computes whether a page is nearing EoL or past EoL based on the `page-release-date` attribute and configured settings.
+It injects the following attributes into each page, making them available for use in UI templates:
+
+- `page-is-nearing-eol`: Indicates if the page is within the warning period before EoL. Calculated using `(page-release-date + supported_months) - warning_weeks`.
+- `page-is-past-eol`: Indicates if the page has passed its EoL. Calculated using `today > (page-release-date + supported_months)`.
+- `page-eol-date`: The calculated EoL date in a human-readable format. Calculated using `page-release-date + supported_months`.
+- `page-eol-doc`: The URL to the supported versions policy or EoL documentation.
+- `page-upgrade-doc`: The Antora resource ID to a document containing upgrade instructions.
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options
+
+To enable and configure the extension, add it to the `antora.extensions` section of your Antora playbook. Define the EoL settings under the `data.eol_settings` key with the following options:
+
+`component` (required):: The component name to which the configuration applies.
+`eol_doc` (required):: A link to the supported versions policy or EoL documentation.
+`upgrade_doc` (required):: A link to the upgrade instructions.
+`supported_months` (optional, default: 12):: The number of months after the publish date when the documentation reaches its EoL.
+`warning_weeks` (optional, default: 6):: The number of weeks before EoL when the documentation is considered to be nearing EoL. Can be used to decide when to notify users of the upcoming EoL status.
+
+[,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/end-of-life'
+      data:
+        eol_settings:
+          - component: 'ROOT'
+            supported_months: 18
+            warning_weeks: 8
+            eol_doc: https://support.redpanda.com/hc/en-us/articles/20617574366743-Redpanda-Supported-Versions
+            upgrade_doc: ROOT:upgrade:index.adoc
+----
+
+==== Registration example
+
+You can register the extension with a customized configuration for different components in your playbook:
+
+[,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/compute-end-of-life'
+      data:
+        eol_settings:
+          - component: 'ROOT'
+            supported_months: 12
+            warning_weeks: 6
+            eol_doc: https://example.com/supported-versions
+            upgrade_doc: ROOT:upgrade:index.adoc
+          - component: 'example-docs'
+            supported_months: 24
+            warning_weeks: 12
+            eol_doc: https://example.com/example-supported-versions
+            upgrade_doc: example-docs:upgrade:index.adoc
+----
+
+
+==== Example Handlebars template:
+
+[,handlebars]
+----
+{{#if page.attributes.is-nearing-eol}}
+  <div class="banner-container nearing-eol">
+    This documentation will reach its end of life on {{page.attributes.eol-date}}.
+    Please <a href="{{resolve-resource page.attributes.upgrade-doc}}">upgrade to a supported version</a>.
+  </div>
+{{else if page.attributes.is-past-eol}}
+  <div class="banner-container past-eol">
+    This documentation reached its end of life on {{page.attributes.eol-date}}.
+    See our <a href="{{page.attributes.eol-doc}}" target="_blank">supported versions policy</a>.
+  </div>
+{{/if}}
+----
+
 === 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.
@@ -463,11 +612,10 @@ antora:
 
 === Replace attributes in attachments
 
-This extension replaces AsciiDoc attribute placeholders with their respective values in attachment files, such as CSS, HTML, and YAML.
+This extension automates the replacement of AsciiDoc attribute placeholders with their respective values within attachment files, such as CSS, HTML, and YAML.
 
-[IMPORTANT]
+[NOTE]
 ====
-- This extension processes attachments only if the component version includes the attribute `replace-attributes-in-attachments: true`.
 - The `@` character is removed from attribute values to prevent potential issues with CSS or HTML syntax.
 - If the same attribute placeholder is used multiple times within a file, all instances will be replaced with the attribute's value.
 ====
@@ -478,14 +626,46 @@ This extension does not require any environment variables.
 
 ==== Configuration options
 
-There are no configurable options for this extension.
+The extension accepts the following configuration options in the Antora playbook:
 
-==== Registration example
+data.replacements (required):: An array of replacement configurations. Each configuration can target multiple components and define specific file patterns and custom replacement rules.
+
+* `components` (array of strings, required): Lists the names of the Antora components whose attachments should undergo attribute replacement.
+
+* `file_patterns` (array of strings, required): Glob patterns specifying which attachment files to process. These patterns determine the files that will undergo attribute replacement based on their paths within the content catalog.
+
+* `custom_replacements` (array of objects, optional): Defines custom search-and-replace rules to be applied to the matched files. Each rule consists of:
+** `search` (string, required): A regular expression pattern to search for within the file content.
+** `replace` (string, required): The string to replace each match found by the `search` pattern.
+
+NOTE: Ensure that `file_patterns` accurately reflect the paths of the attachments you want to process. Overly broad patterns may include unintended files, while overly restrictive patterns might exclude necessary resources.
+
+==== Registration Example
+
+This is an example of how to register and configure the `replace-attributes-in-attachments` extension in your Antora playbook. This example demonstrates defining multiple replacement configurations, each targeting different components and specifying their own file patterns and custom replacements.
 
 ```yaml
 antora:
   extensions:
-  - '@redpanda-data/docs-extensions-and-macros/extensions/replace-attributes-in-attachments'
+    - require: './extensions/replace-attributes-in-attachments'
+      data:
+        replacements:
+          - components:
+              - 'ROOT'
+              - 'redpanda-labs'
+            file_patterns:
+              - '**/docker-compose.yaml'
+              - '**/docker-compose.yml'
+            custom_replacements:
+              - search: ''\\$\\{CONFIG_FILE:[^}]*\\}''
+                replace: 'console.yaml'
+          - components:
+              - 'API'
+            file_patterns:
+              - '**/api-docs/**/resources/**'
+            custom_replacements:
+              - search: '\\$\\{API_ENDPOINT:[^}]*\\}'
+                replace: 'https://api.example.com'
 ```
 
 === Aggregate terms

package/extensions/archive-attachments.js

@@ -0,0 +1,183 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const tar = require("tar");
+const micromatch = require("micromatch");
+const { PassThrough } = require("stream");
+const os = require("os"); // For accessing the system's temp directory
+
+/**
+ * Create a tar.gz archive in memory.
+ * @param {string} tempDir - The temporary directory containing files to archive.
+ * @returns {Promise<Buffer>} - A promise that resolves to the tar.gz buffer.
+ */
+async function createTarInMemory(tempDir) {
+  return new Promise((resolve, reject) => {
+    const pass = new PassThrough();
+    const chunks = [];
+
+    pass.on("data", (chunk) => chunks.push(chunk));
+    pass.on("error", (error) => reject(error));
+    pass.on("end", () => resolve(Buffer.concat(chunks)));
+
+    tar
+      .create(
+        {
+          gzip: true,
+          cwd: tempDir,
+        },
+        ["."]
+      )
+      .pipe(pass)
+      .on("error", (err) => reject(err));
+  });
+}
+
+module.exports.register = function ({ config }) {
+  const logger = this.getLogger("archive-attachments-extension");
+  const archives = config.data?.archives || [];
+
+  // Validate configuration
+  if (!archives.length) {
+    logger.info("No `archives` configurations provided. Archive creation skipped.");
+    return;
+  }
+
+  this.on("beforePublish", async ({ contentCatalog, siteCatalog }) => {
+    logger.info("Starting archive creation process");
+
+    const components = contentCatalog.getComponents();
+
+    for (const archiveConfig of archives) {
+      const { output_archive, component, file_patterns } = archiveConfig;
+
+      // Validate individual archive configuration
+      if (!output_archive) {
+        logger.warn("An `archive` configuration is missing `output_archive`. Skipping this archive.");
+        continue;
+      }
+      if (!component) {
+        logger.warn(`Archive "${output_archive}" is missing component config. Skipping this archive.`);
+        continue;
+      }
+      if (!file_patterns || !file_patterns.length) {
+        logger.warn(`Archive "${output_archive}" has no file_patterns config. Skipping this archive.`);
+        continue;
+      }
+
+      logger.debug(`Processing archive: ${output_archive} for component: ${component}`);
+
+      // Find the specified component
+      const comp = components.find((c) => c.name === component);
+      if (!comp) {
+        logger.warn(`Component "${component}" not found. Skipping archive "${output_archive}".`);
+        continue;
+      }
+
+      for (const compVer of comp.versions) {
+        const compName = comp.name;
+        const compVersion = compVer.version;
+        const latest = comp.latest?.version || "not latest";
+
+        const isLatest = latest === compVersion;
+
+        logger.debug(`Processing component version: ${compName}@${compVersion}`);
+
+        // Gather attachments for this component version
+        const attachments = contentCatalog.findBy({
+          component: compName,
+          version: compVersion,
+          family: "attachment",
+        });
+
+        logger.debug(`Found ${attachments.length} attachments for ${compName}@${compVersion}`);
+
+        if (!attachments.length) {
+          logger.debug(`No attachments found for ${compName}@${compVersion}, skipping.`);
+          continue;
+        }
+
+        // Filter attachments based on file_patterns
+        const attachmentsSegment = "_attachments/";
+        const matched = attachments.filter((attachment) =>
+          micromatch.isMatch(attachment.out.path, file_patterns)
+        );
+
+        logger.debug(`Matched ${matched.length} attachments for ${compName}@${compVersion}`);
+
+        if (!matched.length) {
+          logger.debug(`No attachments matched patterns for ${compName}@${compVersion}, skipping.`);
+          continue;
+        }
+
+        // Create a temporary directory and write matched attachments
+        let tempDir;
+        try {
+          tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `${compName}-${compVersion}-`));
+          logger.debug(`Created temporary directory: ${tempDir}`);
+
+          for (const attachment of matched) {
+            const relPath = attachment.out.path;
+            const attachmentsIndex = relPath.indexOf(attachmentsSegment);
+
+            if (attachmentsIndex === -1) {
+              logger.warn(`'${attachmentsSegment}' segment not found in path: ${relPath}. Skipping this file.`);
+              continue;
+            }
+
+            // Extract the path starting after '_attachments/'
+            const relativePath = relPath.substring(attachmentsIndex + attachmentsSegment.length);
+
+            const destPath = path.join(tempDir, relativePath);
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            fs.writeFileSync(destPath, attachment.contents);
+            logger.debug(`Written file to tempDir: ${destPath}`);
+          }
+
+          // Asynchronously create the tar.gz archive in memory
+          try {
+            logger.debug(`Starting tar creation for ${compName}@${compVersion}`);
+            const archiveBuffer = await createTarInMemory(tempDir);
+            logger.debug(`Tar creation completed for ${compName}@${compVersion}`);
+
+            // Define the output path for the archive in the site
+            const archiveOutPath = `${compVersion ? compVersion + "-" : ""}${output_archive}`.toLowerCase();
+
+            // Add the archive to siteCatalog
+            siteCatalog.addFile({
+              contents: archiveBuffer,
+              out: { path: archiveOutPath },
+            });
+
+            if (isLatest) {
+              siteCatalog.addFile({
+                contents: archiveBuffer,
+                out: { path: path.basename(output_archive) },
+              });
+            }
+
+            logger.info(`Archive "${archiveOutPath}" added to site.`);
+          } catch (error) {
+            logger.error(`Error creating tar archive for ${compName}@${compVersion}:`, error);
+            continue; // Skip further processing for this version
+          }
+        } catch (error) {
+          logger.error(`Error processing ${compName}@${compVersion}:`, error);
+        } finally {
+          // Clean up the temporary directory
+          if (tempDir) {
+            try {
+              fs.rmSync(tempDir, { recursive: true, force: true });
+              logger.debug(`Cleaned up temporary directory: ${tempDir}`);
+            } catch (cleanupError) {
+              logger.error(`Error cleaning up tempDir "${tempDir}":`, cleanupError);
+            }
+          }
+        }
+      }
+    }
+
+    logger.info("Archive creation process completed");
+  });
+};

package/extensions/compute-end-of-life.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const calculateEOL = require('./util/calculate-eol.js');
+
+module.exports.register = function ({ config }) {
+  this.on('contentClassified', ({ contentCatalog }) => {
+    const logger = this.getLogger("compute-end-of-life-extension");
+
+    // Extract EOL configuration from the config object
+    const eolConfigs = config.data?.eol_settings || [];
+    if (!Array.isArray(eolConfigs) || eolConfigs.length === 0) {
+      logger.warn('No end-of-life settings found in configuration.');
+      return;
+    }
+
+    eolConfigs.forEach(({ component: componentName, supported_months, warning_weeks, eol_doc, upgrade_doc }) => {
+      if (!eol_doc || !upgrade_doc) {
+        logger.error(
+          `End-of-life configuration for component "${component}" is missing required attributes. ` +
+          `Ensure both "eol_doc" and "upgrade_doc" are specified.`
+        );
+        return;
+      }
+      const resolvedEOLMonths = supported_months && supported_months > 0 ? supported_months : 12; // Default: 12 months
+      const resolvedWarningWeeks = warning_weeks && warning_weeks > 0 ? warning_weeks : 6; // Default: 6 weeks
+
+      logger.info(
+        `Processing component: ${componentName} with end-of-life months: ${resolvedEOLMonths}, Warning weeks: ${resolvedWarningWeeks}`
+      );
+
+      const component = contentCatalog.getComponents().find((c) => c.name === componentName);
+
+      if (!component) {
+        logger.warn(`Component not found: ${componentName}`);
+        return;
+      }
+
+      component.versions.forEach(({ asciidoc, version }) => {
+        const releaseDate = asciidoc.attributes['page-release-date'];
+        if (releaseDate) {
+          // Pass resolved configuration to calculateEOL
+          const eolInfo = calculateEOL(releaseDate, resolvedEOLMonths, resolvedWarningWeeks, logger);
+          Object.assign(asciidoc.attributes, {
+            'page-is-nearing-eol': eolInfo.isNearingEOL.toString(),
+            'page-is-past-eol': eolInfo.isPastEOL.toString(),
+            'page-eol-date': eolInfo.eolDate,
+            'page-eol-doc': eol_doc,
+            'page-upgrade-doc': upgrade_doc,
+          });
+        } else {
+          logger.warn(`No release date found for component: ${componentName}. Make sure to set {page-release-date} in the antora.yml of the component version ${version}.`);
+        }
+      });
+    });
+  });
+};

package/extensions/replace-attributes-in-attachments.js

@@ -1,80 +1,228 @@
 'use strict';
+
 const semver = require('semver');
+const micromatch = require('micromatch');
+const formatVersion = require('./util/format-version.js');
+const sanitize = require('./util/sanitize-attributes.js');
+
+/**
+ * Registers the replace attributes extension with support for multiple replacements.
+ * Each replacement configuration can target specific components and file patterns.
+ *
+ * Configuration Structure:
+ * data:
+ *   replacements:
+ *     - components:
+ *         - 'ComponentName1'
+ *         - 'ComponentName2'
+ *       file_patterns:
+ *         - 'path/to/attachments/**'
+ *         - '/another/path/*.adoc'
+ *       custom_replacements:
+ *         - search: 'SEARCH_REGEX_PATTERN'
+ *           replace: 'Replacement String'
+ *         - ...
+ */
+module.exports.register = function ({ config }) {
+  const logger = this.getLogger('replace-attributes-extension');
+  const replacements = config.data?.replacements || [];
+
+  // Validate configuration
+  if (!replacements.length) {
+    logger.info('No `replacements` configurations provided. Replacement process skipped.');
+    return;
+  }
+
+  // Precompile all glob matchers for performance
+  replacements.forEach((replacementConfig, index) => {
+    const { components, file_patterns } = replacementConfig;
+
+    if (!components || !Array.isArray(components) || !components.length) {
+      logger.warn(`Replacement configuration at index ${index} is missing 'components'. Skipping this replacement configuration.`);
+      replacementConfig.matchers = null;
+      return;
+    }
+
+    if (!file_patterns || !file_patterns.length) {
+      logger.warn(`Replacement configuration at index ${index} is missing 'file_patterns'. Skipping this replacement configuration.`);
+      replacementConfig.matchers = null;
+      return;
+    }
+
+    replacementConfig.matchers = micromatch.matcher(file_patterns, { dot: true });
+  });
+
+  // Precompile all user replacements for each replacement configuration
+  replacements.forEach((replacementConfig, index) => {
+    const { custom_replacements } = replacementConfig;
+    if (!custom_replacements || !custom_replacements.length) {
+      replacementConfig.compiledCustomReplacements = [];
+      return;
+    }
+    replacementConfig.compiledCustomReplacements = custom_replacements.map(({ search, replace }) => {
+      try {
+        return {
+          regex: new RegExp(search, 'g'),
+          replace,
+        };
+      } catch (err) {
+        logger.error(`Invalid regex pattern in custom_replacements for replacement configuration at index ${index}: "${search}"`, err);
+        return null;
+      }
+    }).filter(Boolean); // Remove any null entries due to invalid regex
+  });
 
-module.exports.register = function () {
   this.on('contentClassified', ({ contentCatalog }) => {
+    // Build a lookup table: [componentName][version] -> componentVersion
     const componentVersionTable = contentCatalog.getComponents().reduce((componentMap, component) => {
-      componentMap[component.name] = component.versions.reduce((versionMap, componentVersion) => {
-        versionMap[componentVersion.version] = componentVersion;
+      componentMap[component.name] = component.versions.reduce((versionMap, compVer) => {
+        versionMap[compVer.version] = compVer;
         return versionMap;
       }, {});
       return componentMap;
     }, {});
 
-    contentCatalog.findBy({ family: 'attachment' }).forEach((attachment) => {
-      const componentVersion = componentVersionTable[attachment.src.component]?.[attachment.src.version];
-      if (!componentVersion?.asciidoc?.attributes) return;
+    // Iterate over each replacement configuration
+    replacements.forEach((replacementConfig, replacementIndex) => {
+      const { components, matchers, compiledCustomReplacements } = replacementConfig;
 
-      const attributes = Object.entries(componentVersion.asciidoc.attributes).reduce((accum, [name, val]) => {
-        const stringValue = String(val);
-        accum[name] = stringValue.endsWith('@') ? sanitizeAttributeValue(stringValue) : stringValue;
-        return accum;
-      }, {});
-
-      let contentString = attachment.contents.toString();
-      let modified = false;
-
-    // Determine if we're using the tag or version attributes
-    // We introduced tag attributes in Self-Managed 24.3
-    const isPrerelease = attributes['page-component-version-is-prerelease'];
-    const componentVersionNumber = formatVersion(componentVersion.version || '');
-    const useTagAttributes = isPrerelease || (componentVersionNumber && semver.gte(componentVersionNumber, '24.3.0') && componentVersion.title === 'Self-Managed');
-
-    // Set replacements based on the condition
-    const redpandaVersion = isPrerelease
-      ? sanitizeAttributeValue(attributes['redpanda-beta-tag'] || '')
-      : (useTagAttributes
-      ? sanitizeAttributeValue(attributes['latest-redpanda-tag'] || '')
-      : sanitizeAttributeValue(attributes['full-version'] || ''));
-
-      const consoleVersion = isPrerelease
-      ? sanitizeAttributeValue(attributes['console-beta-tag'] || '')
-      : (useTagAttributes
-      ? sanitizeAttributeValue(attributes['latest-console-tag'] || '')
-      : sanitizeAttributeValue(attributes['latest-console-version'] || ''));
-
-      const redpandaRepo = isPrerelease ? 'redpanda-unstable' : 'redpanda';
-      const consoleRepo = 'console';
-
-      // YAML-specific replacements
-      if (attachment.out.path.endsWith('.yaml') || attachment.out.path.endsWith('.yml')) {
-        contentString = replacePlaceholder(contentString, /\$\{REDPANDA_DOCKER_REPO:[^\}]*\}/g, redpandaRepo);
-        contentString = replacePlaceholder(contentString, /\$\{CONSOLE_DOCKER_REPO:[^\}]*\}/g, consoleRepo);
-        contentString = replacePlaceholder(contentString, /\$\{REDPANDA_VERSION[^\}]*\}/g, redpandaVersion);
-        contentString = replacePlaceholder(contentString, /\$\{REDPANDA_CONSOLE_VERSION[^\}]*\}/g, consoleVersion);
-        modified = true;
+      if (!components || !matchers) {
+        // Already logged and skipped in precompilation
+        return;
       }
 
-      // General attribute replacements (excluding uppercase with underscores)
-      const result = contentString.replace(/\{([a-z][\p{Alpha}\d_-]*)\}/gu, (match, name) => {
-        if (!(name in attributes)) return match;
-        modified = true;
-        return attributes[name];
-      });
+      components.forEach((componentName) => {
+        const comp = contentCatalog.getComponents().find(c => c.name === componentName);
+        if (!comp) {
+          logger.warn(`Component "${componentName}" not found. Skipping replacement configuration at index ${replacementIndex}.`);
+          return;
+        }
 
-      if (modified) attachment.contents = Buffer.from(result);
-    });
-  });
+        comp.versions.forEach((compVer) => {
+          const compName = comp.name;
+          const compVersion = compVer.version;
 
-  // Helper function to replace placeholders with attribute values
-  function replacePlaceholder(content, regex, replacement) {
-    return content.replace(regex, replacement);
-  }
+          logger.debug(`Processing component version: ${compName}@${compVersion} for replacement configuration at index ${replacementIndex}`);
+
+          // Gather attachments for this component version
+          const attachments = contentCatalog.findBy({
+            component: compName,
+            version: compVersion,
+            family: 'attachment',
+          });
+
+          logger.debug(`Found ${attachments.length} attachments for ${compName}@${compVersion}`);
+
+          if (!attachments.length) {
+            logger.debug(`No attachments found for ${compName}@${compVersion}, skipping.`);
+            return;
+          }
+
+          // Filter attachments based on file_patterns
+          const matched = attachments.filter((attachment) => {
+            const filePath = attachment.out.path;
+            return matchers(filePath);
+          });
+
+          logger.debug(`Matched ${matched.length} attachments for ${compName}@${compVersion} in replacement configuration at index ${replacementIndex}`);
 
-  const sanitizeAttributeValue = (value) => String(value).replace('@', '');
+          if (!matched.length) {
+            logger.debug(`No attachments matched patterns for ${compName}@${compVersion} in replacement configuration at index ${replacementIndex}, skipping.`);
+            return;
+          }
 
-  const formatVersion = (version) => {
-    if (!version) return null;
-    return semver.valid(version) ? version : `${version}.0`;
-  };
+          // Process each matched attachment
+          matched.forEach((attachment) => {
+            const { component: attComponent, version: attVersion } = attachment.src;
+            const componentVer = componentVersionTable[attComponent]?.[attVersion];
+
+            if (!componentVer?.asciidoc?.attributes) {
+              // Skip attachments without asciidoc attributes
+              return;
+            }
+
+            const filePath = attachment.out.path;
+
+            logger.debug(`Processing attachment: ${filePath} for replacement configuration at index ${replacementIndex}`);
+
+            // Compute dynamic replacements specific to this componentVersion
+            const dynamicReplacements = getDynamicReplacements(componentVer, logger);
+
+            // Precompile dynamic replacements for this attachment
+            const compiledDynamicReplacements = dynamicReplacements.map(({ search, replace }) => ({
+              regex: new RegExp(search, 'g'),
+              replace,
+            }));
+
+            // Combine dynamic and user replacements
+            const allReplacements = [...compiledDynamicReplacements, ...compiledCustomReplacements];
+
+            // Convert buffer to string once
+            let contentStr = attachment.contents.toString('utf8');
+
+            // Apply all replacements in a single pass
+            contentStr = applyAllReplacements(contentStr, allReplacements);
+
+            // Expand AsciiDoc attributes
+            contentStr = expandAsciiDocAttributes(contentStr, componentVer.asciidoc.attributes);
+
+            // Convert back to buffer
+            attachment.contents = Buffer.from(contentStr, 'utf8');
+          });
+        });
+      });
+    });
+  })
 };
+
+// Build dynamic placeholder replacements
+function getDynamicReplacements(componentVersion, logger) {
+  const attrs = componentVersion.asciidoc.attributes;
+  const isPrerelease = attrs['page-component-version-is-prerelease'];
+  const versionNum = formatVersion(componentVersion.version || '', semver);
+  const is24_3plus =
+    versionNum && semver.gte(versionNum, '24.3.0') && componentVersion.title === 'Self-Managed';
+  const useTagAttributes = isPrerelease || is24_3plus;
+
+  // Derive Redpanda / Console versions
+  const redpandaVersion = isPrerelease
+    ? sanitize(attrs['redpanda-beta-tag'] || '')
+    : useTagAttributes
+    ? sanitize(attrs['latest-redpanda-tag'] || '')
+    : sanitize(attrs['full-version'] || '');
+  const consoleVersion = isPrerelease
+    ? sanitize(attrs['console-beta-tag'] || '')
+    : useTagAttributes
+    ? sanitize(attrs['latest-console-tag'] || '')
+    : sanitize(attrs['latest-console-version'] || '');
+
+  const redpandaRepo = isPrerelease ? 'redpanda-unstable' : 'redpanda';
+  const consoleRepo = 'console';
+
+  return [
+    { search: '\\$\\{REDPANDA_DOCKER_REPO:[^}]*\\}', replace: redpandaRepo },
+    { search: '\\$\\{CONSOLE_DOCKER_REPO:[^}]*\\}', replace: consoleRepo },
+    { search: '\\$\\{REDPANDA_VERSION[^}]*\\}', replace: redpandaVersion },
+    { search: '\\$\\{REDPANDA_CONSOLE_VERSION[^}]*\\}', replace: consoleVersion },
+  ];
+}
+
+// Apply an array of { regex, replace } to a string in a single pass
+function applyAllReplacements(content, replacements) {
+  // Sort replacements by descending length of regex source to handle overlapping patterns
+  replacements.sort((a, b) => b.regex.source.length - a.regex.source.length);
+
+  replacements.forEach(({ regex, replace }) => {
+    content = content.replace(regex, replace);
+  });
+
+  return content;
+}
+
+// Expand all existing attributes
+function expandAsciiDocAttributes(content, attributes) {
+  return content.replace(/\{([a-z][\p{Alpha}\d_-]*)\}/gu, (match, name) => {
+    if (!(name in attributes)) return match;
+    return sanitize(attributes[name]);
+  });
+}

package/extensions/util/calculate-eol.js

@@ -0,0 +1,55 @@
+'use strict';
+
+module.exports = (releaseDate, eolMonths, warningWeeks, logger) => {
+  if (!releaseDate) {
+    logger.warn(
+      'No release date provided. Make sure to set {page-release-date} in the antora.yml of the component.'
+    );
+    return null;
+  }
+
+  // Parse the input date string YYYY-MM-DD in UTC
+  const parseUTCDate = (dateString) => {
+    const [year, month, day] = dateString.split('-').map(Number);
+    // month - 1 because JS months are 0-based
+    // https://www.w3schools.com/jsref/jsref_getmonth.asp
+    return new Date(Date.UTC(year, month - 1, day));
+  };
+
+  const targetDate = parseUTCDate(releaseDate);
+
+  if (isNaN(targetDate.getTime())) {
+    logger.warn('Invalid release date format:', releaseDate);
+    return null;
+  }
+
+  // Calculate EoL date in UTC
+  const eolDate = new Date(targetDate.getTime()); // clone
+  eolDate.setUTCMonth(eolDate.getUTCMonth() + eolMonths);
+
+  // Calculate the threshold for warning (X weeks before EoL) in UTC
+  const weeksBeforeEOL = new Date(eolDate.getTime());
+  weeksBeforeEOL.setUTCDate(weeksBeforeEOL.getUTCDate() - warningWeeks * 7);
+
+  // Compare times in milliseconds to avoid timezone confusion
+  const nowMs = Date.now();
+  const eolMs = eolDate.getTime();
+  const warningMs = weeksBeforeEOL.getTime();
+
+  const isNearingEOL = nowMs >= warningMs && nowMs < eolMs;
+  const isPastEOL = nowMs > eolMs;
+
+  // Format the EoL date in UTC
+  const humanReadableEOLDate = new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC', // Ensure UTC in output
+  }).format(eolDate);
+
+  return {
+    isNearingEOL,
+    isPastEOL,
+    eolDate: humanReadableEOLDate, // For example "March 1, 2025"
+  };
+};

package/extensions/util/custom-stringify.js

@@ -0,0 +1,19 @@
+function customStringify(obj) {
+  return JSON.stringify(obj, (key, value) => {
+    if (value instanceof Map) {
+      return {
+        type: 'Map',
+        value: Array.from(value.entries())
+      };
+    } else if (value instanceof Set) {
+      return {
+        type: 'Set',
+        value: Array.from(value)
+      };
+    } else if (typeof value === 'function') {
+      return value.toString();
+    } else {
+      return value;
+    }
+  }, 2);
+}

package/extensions/util/format-version.js

@@ -0,0 +1,7 @@
+/* -----------------------------
+   Utility: ensure valid semver or fallback
+----------------------------- */
+module.exports = (version, semver) => {
+  if (!version) return null;
+  return semver.valid(version) ? version : `${version}.0`;
+}

package/extensions/util/sanitize-attributes.js

@@ -0,0 +1,6 @@
+/* -----------------------------
+   Utility: remove trailing '@'
+----------------------------- */
+module.exports = (val) => {
+  return String(val).replace('@', '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.11.2",
+  "version": "4.1.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -30,8 +30,10 @@
       "require": "./extensions/unlisted-pages.js"
     },
     "./extensions/replace-attributes-in-attachments": "./extensions/replace-attributes-in-attachments.js",
+    "./extensions/archive-attachments": "./extensions/archive-attachments.js",
     "./extensions/add-pages-to-root": "./extensions/add-pages-to-root.js",
     "./extensions/collect-bloblang-samples": "./extensions/collect-bloblang-samples.js",
+    "./extensions/compute-end-of-life": "./extensions/compute-end-of-life.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",
@@ -72,9 +74,11 @@
     "html-entities": "2.3",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
+    "micromatch": "^4.0.8",
     "node-html-parser": "5.4.2-0",
     "papaparse": "^5.4.1",
-    "semver": "^7.6.0"
+    "semver": "^7.6.0",
+    "tar": "^7.4.3"
   },
   "devDependencies": {
     "@antora/cli": "3.1.4",

package/extensions/util/customStringify.js

@@ -1,19 +0,0 @@
-function customStringify(obj) {
-    return JSON.stringify(obj, (key, value) => {
-        if (value instanceof Map) {
-            return {
-                type: 'Map',
-                value: Array.from(value.entries())
-            };
-        } else if (value instanceof Set) {
-            return {
-                type: 'Set',
-                value: Array.from(value)
-            };
-        } else if (typeof value === 'function') {
-            return value.toString();
-        } else {
-            return value;
-        }
-    }, 2);
-}