@redpanda-data/docs-extensions-and-macros 3.5.4 → 3.5.6

package/README.adoc

@@ -38,17 +38,17 @@ When you have Node.js installed, use the following command to install the `antor
 npm i @redpanda-data/docs-extensions-and-macros
 ----
 
-To use the development version instead, refer to the <<development-quickstart,Development Quickstart>>.
+To use the development version, refer to the <<development-quickstart,Development Quickstart>>.
 
 == Antora Extensions
 
-This section documents the Antora extensions that are provided by this library and how to configure them.
+This section documents the Antora extensions provided by this library and how to configure them.
 
 IMPORTANT: Ensure you register each extension under the `antora.extensions` key in the playbook, not the `asciidoc.extensions` key.
 
 === 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 following template: `algolia-<component>-<version>.json`.
+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`.
 
 NOTE: Only pages that include an `<article>` element with the `doc` class are indexed.
 
@@ -127,9 +127,19 @@ antora:
 
 This extension fetches the latest release versions from GitHub.
 
-The latest versions of Redpanda Console and Redpanda Connect are made available to all versions of all Antora components.
+The following attributes are available to all versions of all Antora components:
 
-The latest Redpanda version and the latest Redpanda Operator version are made available to the latest version of the `ROOT` component (Redpanda docs).
+`latest-console-version`: The latest release version of Redpanda Console.
+`latest-connect-version`: The latest release version of Redpanda Connect.
+`redpanda-beta-version`: The latest RC version of Redpanda.
+`redpanda-beta-commit`: The commit hash for the latest RC version of Redpanda.
+
+The following attributes are available to the latest version of the `ROOT` component (Redpanda docs):
+
+`full-version`: The latest release version of Redpanda.
+`latest-release-commit`: The commit hash for the latest release version of Redpanda.
+`latest-operator-version`: The latest release version of the Redpanda Operator.
+`latest-redpanda-helm-chart-version`: The latest release version of the Redpanda Helm chart.
 
 ==== Environment variables
 

package/extensions/modify-connect-tag-playbook.js

@@ -14,7 +14,7 @@ module.exports.register = function ({ config }) {
         if (source) {
           const latestTag = await GetLatestConnectTag();
           if (latestTag) {
-            source.tags[0] = latestTag;
+            source.tags[0] = `v${latestTag}`;
             this.updateVariables({ playbook });
           }
         }

package/extensions/produce-redirects.js

@@ -11,7 +11,7 @@ module.exports.register = function () {
     this.replaceFunctions({
       produceRedirects (playbook, aliases) {
         if ('findBy' in aliases) aliases = aliases.findBy({ family: 'alias' }) // @deprecated remove in Antora 4
-        if (!aliases.length) return []
+        if (!(aliases = aliases.filter((it) => it.pub.url !== it.rel.pub.url)).length) return []
         let siteUrl = playbook.site.url
         if (siteUrl) siteUrl = stripTrailingSlash(siteUrl, '')
         const directoryRedirects = (playbook.urls.htmlExtensionStyle || 'default') !== 'default'
@@ -32,7 +32,6 @@ module.exports.register = function () {
           default:
             return unpublish(aliases)
         }
-        return produceRedirectsDelegate.call(this, playbook, aliases)
       }
     })
   })
@@ -72,7 +71,6 @@ function extractUrlPath (url) {
 
 function createHttpdHtaccess (files, urlPath, directoryRedirects = false) {
   const rules = files.reduce((accum, file) => {
-    if (isRedirectLoop(file)) return accum
     delete file.out
     let fromUrl = file.pub.url
     fromUrl = ~fromUrl.indexOf('%20') ? `'${urlPath}${fromUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + fromUrl
@@ -97,7 +95,6 @@ function createHttpdHtaccess (files, urlPath, directoryRedirects = false) {
 // however, we keep it when generating the rules for clarity
 function createNetlifyRedirects (files, urlPath, addDirectoryRedirects = false, useForceFlag = true) {
   const rules = files.reduce((accum, file) => {
-    if (isRedirectLoop(file)) return accum
     delete file.out
     const fromUrl = urlPath + file.pub.url
     const toUrl = urlPath + file.rel.pub.url
@@ -117,7 +114,6 @@ function createNetlifyRedirects (files, urlPath, addDirectoryRedirects = false,
 
 function createNginxRewriteConf (files, urlPath) {
   const rules = files.map((file) => {
-    if (isRedirectLoop(file)) return ''
     delete file.out
     let fromUrl = file.pub.url
     fromUrl = ~fromUrl.indexOf('%20') ? `'${urlPath}${fromUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + fromUrl
@@ -135,7 +131,6 @@ function createNginxRewriteConf (files, urlPath) {
 
 function populateStaticRedirectFiles(files, siteUrl) {
   for (const file of files) {
-    if (isRedirectLoop(file)) continue
     const content = createStaticRedirectContents(file, siteUrl) + '\n';
     file.contents = Buffer.from(content);
   }
@@ -166,8 +161,3 @@ function regexpEscape (str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // don't escape "-" since it's meaningless in a literal
 }
 
-function isRedirectLoop (file) {
-  if (file.pub.url === file.rel.pub.url) return true
-  return false
-}
-

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

@@ -1,40 +1,51 @@
-module.exports.register = function ({ config }) {
-  const { family = 'attachment' } = config;
-  const logger = this.getLogger('replace-attributes-in-attachments-extension');
+'use strict';
 
+module.exports.register = function () {
   const sanitizeAttributeValue = (value) => String(value).replace("@", "");
+  this.on('contentClassified', ({ contentCatalog }) => {
+    const componentVersionTable = contentCatalog.getComponents().reduce((componentMap, component) => {
+      componentMap[component.name] = component.versions.reduce((versionMap, componentVersion) => {
+        versionMap[componentVersion.version] = componentVersion;
+        return versionMap;
+      }, {});
+      return componentMap;
+    }, {});
 
-  this.on('contentClassified', ({contentCatalog}) => {
-    for (const { versions } of contentCatalog.getComponents()) {
-      for (const { name: component, version, asciidoc } of versions) {
-        const attachments = contentCatalog.findBy({ component, version, family });
-        if (component == 'api') continue;
-        for (const attachment of attachments) {
-          let contentString = attachment['_contents'].toString('utf8');
-          if (!asciidoc.attributes) continue;
-
-          // Replace general attributes
-          for (const key in asciidoc.attributes) {
-            const placeholder = "{" + key + "}";
-            const sanitizedValue = sanitizeAttributeValue(asciidoc.attributes[key]);
-            contentString = contentString.replace(new RegExp(placeholder, 'g'), sanitizedValue);
-          }
+    contentCatalog.findBy({ family: 'attachment' }).forEach((attachment) => {
+      const componentVersion = componentVersionTable[attachment.src.component][attachment.src.version];
+      let attributes = componentVersion.asciidoc?.attributes;
+      if (!attributes) return;
+      attributes = Object.entries(attributes).reduce((accum, [name, val]) => {
+        const stringValue = String(val); // Ensure val is a string
+        accum[name] = stringValue.endsWith('@') ? stringValue.slice(0, stringValue.length - 1) : stringValue;
+        return accum;
+      }, {});
+      let modified;
+      let contentString = attachment.contents.toString();
+      // Specific replacements for YAML files
+      if (attachment.out.path.endsWith('.yaml') || attachment.out.path.endsWith('.yml')) {
+        const redpandaVersionRegex = /(\$\{REDPANDA_VERSION[^\}]*\})/g;
+        const redpandaConsoleVersionRegex = /(\$\{REDPANDA_CONSOLE_VERSION[^\}]*\})/g;
+        let fullVersion = attributes['full-version'] ? sanitizeAttributeValue(attributes['full-version']) : '';
+        const latestConsoleVersion = attributes['latest-console-version'] ? sanitizeAttributeValue(attributes['latest-console-version']) : '';
 
+        if (attributes['page-component-version-is-prerelease'] === 'true') {
+          fullVersion = attributes['redpanda-beta-version'] ? sanitizeAttributeValue(attributes['redpanda-beta-version']) : fullVersion;
+        }
 
-          // Specific replacements for YAML files
-          if (attachment.out.path.endsWith('.yaml') || attachment.out.path.endsWith('.yml')) {
-            const redpandaVersionRegex = /(\$\{REDPANDA_VERSION[^\}]*\})/g;
-            const redpandaConsoleVersionRegex = /(\$\{REDPANDA_CONSOLE_VERSION[^\}]*\})/g;
-            const fullVersion = asciidoc.attributes['full-version'] ? sanitizeAttributeValue(asciidoc.attributes['full-version']) : '';
-            const latestConsoleVersion = asciidoc.attributes['latest-console-version'] ? sanitizeAttributeValue(asciidoc.attributes['latest-console-version']) : '';
+        contentString = contentString.replace(redpandaVersionRegex, fullVersion);
+        contentString = contentString.replace(redpandaConsoleVersionRegex, latestConsoleVersion);
+      }
 
-            contentString = contentString.replace(redpandaVersionRegex, fullVersion);
-            contentString = contentString.replace(redpandaConsoleVersionRegex, latestConsoleVersion);
-          }
+      const result = contentString.replace(/\{([\p{Alpha}\d_][\p{Alpha}\d_-]*)\}/gu, (match, name) => {
+        if (!(name in attributes)) return match;
+        modified = true;
+        let value = attributes[name];
+        if (value.endsWith('@')) value = value.slice(0, value.length - 1);
+        return value;
+      });
 
-          attachment['_contents'] = Buffer.from(contentString, "utf-8");
-        }
-      }
-    }
+      if (modified) attachment.contents = Buffer.from(result);
+    });
   });
-}
+};

package/extensions/unlisted-pages.js

@@ -7,10 +7,8 @@ module.exports.register = function ({ config }) {
   this.on('navigationBuilt', ({ siteCatalog, contentCatalog }) => {
     contentCatalog.getComponents().forEach(({ versions }) => {
       versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
-        if (component === 'api') return;
+        if (component === 'api' || component === 'redpanda-labs') return;
         if (!nav) return;
-        const currentComponent = contentCatalog.getComponent(component);
-        const prerelease = currentComponent && currentComponent.latestPrerelease ? currentComponent.latestPrerelease : false;
 
         const navEntriesByUrl = getNavEntriesByUrl(nav);
         const unlistedPages = contentCatalog
@@ -30,10 +28,7 @@ module.exports.register = function ({ config }) {
             return collector;
           }, []);
 
-        if (unlistedPages.length && component === 'redpanda-connect') {
-          // Some component pages for Redpanda Connect are autogenerated. This function tries to add unlisted component pages to the nav in case a new one gets created without updating the nav.
-          addRedpandaConnectPagesToNav(nav[0].items, unlistedPages);
-        } else if (unlistedPages.length && addToNavigation) {
+        if (unlistedPages.length && addToNavigation) {
           nav.push({
             content: unlistedPagesHeading,
             items: unlistedPages.map((page) => {
@@ -55,33 +50,6 @@ function getNavEntriesByUrl(items = [], accum = {}) {
   return accum;
 }
 
-function addRedpandaConnectPagesToNav(navItems, pages) {
-  // get the Components nav section
-  let componentsSection = navItems.find(item => item.content === 'Components');
-  if (!componentsSection) return;
-
-  pages.forEach(page => {
-    const dirname = page.out.dirname;
-    if (!dirname.includes('/components/')) return;
-    const heading = page.asciidoc.attributes.doctitle;
-    const pathParts = dirname.split('/').slice(2); // Get the type
-    // get existing nav items inside the Components tree
-    let currentLevel = componentsSection.items;
-
-    pathParts.forEach((part, index) => {
-      const capitalizedPart = part.charAt(0).toUpperCase() + part.slice(1);
-      let section = currentLevel.find(item => item.content === capitalizedPart);
-      if (!section) {
-        section = { content: capitalizedPart, items: [], root: index === 0 };
-        currentLevel.push(section);
-      }
-      currentLevel = section.items;
-    });
-
-    currentLevel.push({ content: page.asciidoc.navtitle || page.src.stem, url: page.pub.url, urlType: 'internal' });
-  });
-}
-
 function removePageFromNav(navItems, urlToRemove) {
   // Remove the page from the navigation items
   for (let i = navItems.length - 1; i >= 0; i--) {

package/extensions/unpublish-pages.js

@@ -14,14 +14,11 @@ module.exports.register = function () {
       pageVersion = page.asciidoc?.attributes['page-component-version'];
       const component = contentCatalog.getComponent(componentName);
 
-      // Check if the page is part of the beta version
-      const isPrerelease = component && pageVersion && component.latestPrerelease && component.latestPrerelease.version === pageVersion;
-
       // Check the conditions for unpublishing the page
       const shouldUnpublish = (
         page.asciidoc?.attributes['page-unpublish'] ||
         (page.asciidoc?.attributes['publish-only-during-beta']
-        && !isPrerelease // No beta version available, meaning the beta period has ended
+        && !page.asciidoc?.attributes['page-component-version-is-prerelease'] // Not part of a beta version, meaning the beta period has ended
       )
       );
 

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

@@ -30,7 +30,13 @@ module.exports.register = function ({ config }) {
 
       const components = await contentCatalog.getComponents()
       components.forEach(component => {
+        let prerelease = component.latestPrerelease;
         component.versions.forEach(({ name, version, asciidoc }) => {
+          // This attribute is used for conditionally rendering content for beta releases.
+          // It is also used in the `unpublish-pages` extension to unpublish beta pages that aren't part of a beta version.
+          if (prerelease && prerelease.version === version) {
+            asciidoc.attributes['page-component-version-is-prerelease'] = 'true'
+          }
           if (LatestConsoleVersion) {
             asciidoc.attributes['latest-console-version'] = `${LatestConsoleVersion}@`
             logger.info(`Set Redpanda Console version to ${LatestConsoleVersion} in ${name} ${version}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.5.4",
+  "version": "3.5.6",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",