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

package/README.adoc

@@ -254,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.

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -33,6 +33,7 @@
     "./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",

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);
-}