@redpanda-data/docs-extensions-and-macros 4.17.3 → 5.0.1

package/extensions/unpublish-pages.js

@@ -1,6 +1,8 @@
 'use strict';
 
 module.exports.register = function () {
+  const logger = this.getLogger('unpublish-pages-extension');
+
   this.on('documentsConverted', ({ siteCatalog, contentCatalog }) => {
     // Get all pages that have an `out` property
     const pages = contentCatalog.getPages((page) => page.out);
@@ -14,6 +16,15 @@ module.exports.register = function () {
       pageVersion = page.asciidoc?.attributes['page-component-version'];
       const component = contentCatalog.getComponent(componentName);
 
+      // Debug logging for ANY page with publish-only-during-beta attribute
+      if (page.asciidoc?.attributes['publish-only-during-beta']) {
+        logger.debug(`Found page with publish-only-during-beta: ${page.src?.relative || page.pub?.url}`);
+        logger.debug(`  - publish-only-during-beta: ${page.asciidoc?.attributes['publish-only-during-beta']}`);
+        logger.debug(`  - page-component-version-is-prerelease: ${page.asciidoc?.attributes['page-component-version-is-prerelease']}`);
+        logger.debug(`  - page-unpublish: ${page.asciidoc?.attributes['page-unpublish']}`);
+        logger.debug(`  - component: ${componentName}, version: ${pageVersion}`);
+      }
+
       // Check the conditions for unpublishing the page
       const shouldUnpublish = (
         page.asciidoc?.attributes['page-unpublish'] ||
@@ -24,6 +35,7 @@ module.exports.register = function () {
 
       // Unpublish the shouldUnpublish pages
       if (shouldUnpublish) {
+        logger.info(`Unpublishing page: ${page.src?.relative || page.pub?.url}`);
         siteCatalog.unpublishedPages.push(page.pub.url)
         delete page.out;
       }

package/extensions/version-fetcher/fetch-latest-docker-tag.js

@@ -6,9 +6,10 @@
  *
  * @param {string} dockerNamespace - The Docker Hub namespace (organization or username)
  * @param {string} dockerRepo - The repository name on Docker Hub
+ * @param {Object} logger - Optional Antora logger instance for logging
  * @returns {Promise<{ latestStableRelease: string|null, latestBetaRelease: string|null }>}
  */
-module.exports = async (dockerNamespace, dockerRepo) => {
+module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
   const { default: fetch } = await import('node-fetch');
 
   try {
@@ -64,7 +65,11 @@ module.exports = async (dockerNamespace, dockerRepo) => {
     };
 
   } catch (error) {
-    console.error('Error fetching Docker tags:', error);
+    if (logger) {
+      logger.error('Error fetching Docker tags:', error);
+    } else {
+      console.error('Error fetching Docker tags:', error);
+    }
     return {
       latestStableRelease: null,
       latestBetaRelease: null

package/extensions/version-fetcher/get-latest-connect.js

@@ -1,10 +1,14 @@
-module.exports = async (github, owner, repo) => {
+module.exports = async (github, owner, repo, logger = null) => {
 
   try {
     const release = await github.rest.repos.getLatestRelease({ owner, repo });
     return release.data.tag_name
   } catch (error) {
-    console.error(error);
+    if (logger) {
+      logger.error(error);
+    } else {
+      console.error(error);
+    }
     return null;
   }
 };

package/extensions/version-fetcher/get-latest-console-version.js

@@ -1,6 +1,6 @@
 const { retryWithBackoff, isRetryableGitHubError } = require('./retry-util');
 
-module.exports = async (github, owner, repo) => {
+module.exports = async (github, owner, repo, logger = null) => {
   const semver = require('semver');
 
   return retryWithBackoff(
@@ -29,7 +29,11 @@ module.exports = async (github, owner, repo) => {
           latestBetaRelease: latestBetaReleaseVersion || null
         };
       } else {
-        console.log("No valid semver releases found.");
+        if (logger) {
+          logger.warn("No valid semver releases found.");
+        } else {
+          console.log("No valid semver releases found.");
+        }
         return { latestStableRelease: null, latestBetaRelease: null };
       }
     },
@@ -38,9 +42,14 @@ module.exports = async (github, owner, repo) => {
       initialDelay: 1000,
       shouldRetry: isRetryableGitHubError,
       operationName: `Fetch Console version from ${owner}/${repo}`
-    }
+    },
+    logger
   ).catch(error => {
-    console.error('Failed to fetch release information after retries:', error);
+    if (logger) {
+      logger.error('Failed to fetch release information after retries:', error);
+    } else {
+      console.error('Failed to fetch release information after retries:', error);
+    }
     return { latestStableRelease: null, latestBetaRelease: null };
   });
 };

package/extensions/version-fetcher/get-latest-redpanda-helm-version-from-operator.js

@@ -8,9 +8,10 @@
  * @param {string} repo - The repository name (redpanda-operator).
  * @param {string} stableDockerTag - The stable docker tag in format v<major>.<minor>.<patch>.
  * @param {string} betaDockerTag - Optional beta docker tag in format v<major>.<minor>.<patch>-beta.
+ * @param {Object} logger - Optional Antora logger instance for logging
  * @returns {Promise<{ latestStableRelease: string|null, latestBetaRelease: string|null }>}
  */
-module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag) => {
+module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag, logger = null) => {
   const yaml = require('js-yaml');
   const path = 'charts/redpanda/chart/Chart.yaml';
 
@@ -29,7 +30,11 @@ module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag) =>
       const versionMatch = dockerTag.match(/^v(\d+)\.(\d+)(?:\.(\d+))?(?:-beta.*)?$/);
 
       if (!versionMatch) {
-        console.error(`Invalid docker tag format: ${dockerTag}`);
+        if (logger) {
+          logger.error(`Invalid docker tag format: ${dockerTag}`);
+        } else {
+          console.error(`Invalid docker tag format: ${dockerTag}`);
+        }
         return null;
       }
 
@@ -55,11 +60,28 @@ module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag) =>
         const version = chartYaml.version || null;
         return version;
       } catch (error) {
-        console.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
+        if (error.status === 404) {
+          // Branch doesn't exist yet - this is expected for unreleased versions
+          if (logger) {
+            logger.warn(`Fetched operator ${dockerTag} from Docker Hub but branch ${branchName} not found in GitHub (source may not be released yet)`);
+          } else {
+            console.warn(`Fetched operator ${dockerTag} from Docker Hub but branch ${branchName} not found in GitHub (source may not be released yet)`);
+          }
+        } else {
+          if (logger) {
+            logger.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
+          } else {
+            console.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
+          }
+        }
         return null;
       }
     } catch (error) {
-      console.error(`Error processing docker tag ${dockerTag}:`, error.message);
+      if (logger) {
+        logger.error(`Error processing docker tag ${dockerTag}:`, error.message);
+      } else {
+        console.error(`Error processing docker tag ${dockerTag}:`, error.message);
+      }
       return null;
     }
   };
@@ -75,7 +97,11 @@ module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag) =>
       latestBetaRelease: betaChartVersion
     };
   } catch (error) {
-    console.error('Failed to fetch chart versions:', error.message);
+    if (logger) {
+      logger.error('Failed to fetch chart versions:', error.message);
+    } else {
+      console.error('Failed to fetch chart versions:', error.message);
+    }
     return {
       latestStableRelease: null,
       latestBetaRelease: null

package/extensions/version-fetcher/get-latest-redpanda-version.js

@@ -1,6 +1,6 @@
 const { retryWithBackoff, isRetryableGitHubError } = require('./retry-util');
 
-module.exports = async (github, owner, repo) => {
+module.exports = async (github, owner, repo, logger = null) => {
   const semver = require('semver');
 
   return retryWithBackoff(
@@ -67,9 +67,14 @@ module.exports = async (github, owner, repo) => {
       initialDelay: 1000,
       shouldRetry: isRetryableGitHubError,
       operationName: `Fetch Redpanda version from ${owner}/${repo}`
-    }
+    },
+    logger
   ).catch(error => {
-    console.error('Failed to fetch Redpanda release information after retries:', error);
+    if (logger) {
+      logger.error('Failed to fetch Redpanda release information after retries:', error);
+    } else {
+      console.error('Failed to fetch Redpanda release information after retries:', error);
+    }
     return { latestRedpandaRelease: null, latestRcRelease: null };
   });
 };

package/extensions/version-fetcher/retry-util.js

@@ -8,9 +8,10 @@
  * @param {number} options.maxDelay - Maximum delay in ms (default: 10000)
  * @param {Function} options.shouldRetry - Function to determine if error is retryable (default: all errors)
  * @param {string} options.operationName - Name for logging
+ * @param {Object} logger - Optional Antora logger instance for logging
  * @returns {Promise<*>} Result of the function
  */
-async function retryWithBackoff(fn, options = {}) {
+async function retryWithBackoff(fn, options = {}, logger = null) {
   const {
     maxRetries = 3,
     initialDelay = 1000,
@@ -37,8 +38,14 @@ async function retryWithBackoff(fn, options = {}) {
       const jitter = Math.random() * 0.3 * baseDelay; // Add up to 30% jitter
       const delay = Math.floor(baseDelay + jitter);
 
-      console.error(`⚠️  ${operationName} failed (attempt ${attempt + 1}/${maxRetries + 1}): ${error.message}`);
-      console.error(`   Retrying in ${delay}ms...`);
+      // Log retry attempt using logger if available, otherwise fall back to console
+      if (logger) {
+        logger.warn(`${operationName} failed (attempt ${attempt + 1}/${maxRetries + 1}): ${error.message}`);
+        logger.warn(`Retrying in ${delay}ms...`);
+      } else {
+        console.error(`⚠️  ${operationName} failed (attempt ${attempt + 1}/${maxRetries + 1}): ${error.message}`);
+        console.error(`   Retrying in ${delay}ms...`);
+      }
 
       // Wait before retrying
       await new Promise(resolve => setTimeout(resolve, delay));

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

@@ -37,10 +37,10 @@ module.exports.register = function ({ config }) {
         latestOperatorResult,
         latestConnectResult,
       ] = await Promise.allSettled([
-        GetLatestRedpandaVersion(github, owner, 'redpanda'),
-        GetLatestDockerTag(dockerNamespace, 'console'),
-        GetLatestDockerTag(dockerNamespace, 'redpanda-operator'),
-        GetLatestConnectVersion(github, owner, 'connect'),
+        GetLatestRedpandaVersion(github, owner, 'redpanda', logger),
+        GetLatestDockerTag(dockerNamespace, 'console', logger),
+        GetLatestDockerTag(dockerNamespace, 'redpanda-operator', logger),
+        GetLatestConnectVersion(github, owner, 'connect', logger),
       ]);
       
       // Get the Helm chart version after we have the operator version (for both stable and beta)
@@ -49,11 +49,12 @@ module.exports.register = function ({ config }) {
       if (latestOperatorResult.status === 'fulfilled') {
         try {
           const helmChartVersions = await GetLatestHelmChartVersionFromOperator(
-            github, 
-            owner, 
-            'redpanda-operator', 
+            github,
+            owner,
+            'redpanda-operator',
             latestOperatorResult.value?.latestStableRelease,
-            latestOperatorResult.value?.latestBetaRelease
+            latestOperatorResult.value?.latestBetaRelease,
+            logger
           );
           
           latestHelmChartResult = { 

package/macros/rp-connect-components.js

@@ -1,4 +1,6 @@
 'use strict';
+const { posix: path } = require('path')
+
 /**
  * Registers macros for use in Redpanda Connect contexts in the Redpanda documentation.
   * @param {Registry} registry - The Antora registry where this block macro is registered.
@@ -1024,7 +1026,32 @@ module.exports.register = function (registry, context) {
       // Filter for the specific connector by name
       const componentRows = csvData.data.filter(row => row.connector.trim().toLowerCase() === name.trim().toLowerCase());
       if (componentRows.length === 0) {
-        console.error(`No data found for connector: ${name}`);
+        console.warn(`No CSV data found for connector: ${name}. The connector may have been removed or renamed.`);
+        // Build link to release notes using content catalog for proper URL resolution
+        const isCloud = attributes['env-cloud'] !== undefined;
+        let whatsNewUrl = isCloud
+          ? '/cloud-data-platform/get-started/whats-new-cloud/'
+          : '/connect/get-started/whats-new/';
+
+        // Try to resolve the page from the content catalog for accurate URLs
+        if (context.contentCatalog && context.file) {
+          const pageSpec = isCloud
+            ? 'cloud-data-platform:get-started:whats-new-cloud.adoc'
+            : 'connect:get-started:whats-new.adoc';
+          const page = context.contentCatalog.resolvePage(pageSpec, context.file.src);
+          if (page) {
+            // For directory-style URLs like /a/b/c/, use the URL directly as the base
+            whatsNewUrl = path.relative(context.file.pub.url, page.pub.url);
+          }
+        }
+
+        // Return a notice for removed/unknown connectors
+        return self.createBlock(parent, 'pass', `
+          <div class="metadata-block">
+            <div class="metadata-content">
+              <p><strong>Available in:</strong> <em>This connector is no longer available. Check the <a href="${whatsNewUrl}">release notes</a> for migration guidance.</em></p>
+            </div>
+          </div>`);
       }
       // Process types and metadata from CSV
       const types = componentRows.map(row => ({
@@ -1041,6 +1068,21 @@ module.exports.register = function (registry, context) {
         const [currentType] = sortedTypes.splice(currentTypeIndex, 1);
         sortedTypes.unshift(currentType);
       }
+
+      // Set context-switcher attribute for UI template to render compact dropdown in sticky bar
+      if (sortedTypes.length > 1) {
+        const contextSwitcherData = {};
+        sortedTypes.forEach(typeObj => {
+          const link = (component === 'Cloud' && typeObj.redpandaCloudUrl) || typeObj.redpandaConnectUrl;
+          contextSwitcherData[typeObj.type.toLowerCase()] = {
+            name: capitalize(typeObj.type),
+            to: link
+          };
+        });
+        // Set as page attribute (not document attribute) so it's accessible in UI template
+        attributes['page-context-switcher'] = JSON.stringify(contextSwitcherData);
+        parent.getDocument().setAttribute('page-context-switcher', JSON.stringify(contextSwitcherData));
+      }
       // Check if the component requires an Enterprise license (based on support level)
       let enterpriseLicenseInfo = '';
       if (component !== 'Cloud') {
@@ -1051,6 +1093,26 @@ module.exports.register = function (registry, context) {
         }
       }
       const isCloudSupported = componentRows.some(row => row.is_cloud_supported === 'y');
+
+      // Set availability attributes for UI template badges with URLs
+      if (isCloudSupported) {
+        const cloudUrl = sortedTypes[0].redpandaCloudUrl;
+        const connectUrl = sortedTypes[0].redpandaConnectUrl;
+
+        if (component === 'Connect' && cloudUrl) {
+          // Viewing Self-Managed, but also available in Cloud - show Cloud badge with link
+          parent.getDocument().setAttribute('cloud-available', 'true');
+          parent.getDocument().setAttribute('cloud-available-url', cloudUrl);
+        } else if (component === 'Cloud' && connectUrl) {
+          // Viewing Cloud, but also available in Self-Managed - show Self-Managed badge with link
+          parent.getDocument().setAttribute('self-managed-available', 'true');
+          parent.getDocument().setAttribute('self-managed-available-url', connectUrl);
+        }
+      } else if (!isCloudSupported && component === 'Connect') {
+        // Only available in Self-Managed - show "Self-Managed Only" badge (no link)
+        parent.getDocument().setAttribute('self-managed-only', 'true');
+      }
+
       let availableInInfo = '';
 
       if (isCloudSupported) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.17.3",
+  "version": "5.0.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -77,6 +77,8 @@
     "./extensions/algolia-indexer/index": "./extensions/algolia-indexer/index.js",
     "./extensions/aggregate-terms": "./extensions/aggregate-terms.js",
     "./extensions/resolve-xrefs-in-attachments": "./extensions/resolve-xrefs-in-attachments.js",
+    "./extensions/unified-navigation": "./extensions/unified-navigation.js",
+    "./extensions/conditional-home-redirect": "./extensions/conditional-home-redirect.js",
     "./macros/glossary": "./macros/glossary.js",
     "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",

package/tools/redpanda-connect/AUTOMATION.md

@@ -306,14 +306,14 @@ Brief summary of what this connector does.
 ====
 Common config::
 +
-include::redpanda-connect:components:partial$examples/inputs/connector_name.adoc[tag=common]
+include::connect:components:partial$examples/inputs/connector_name.adoc[tag=common]
 
 Advanced config::
 +
-include::redpanda-connect:components:partial$examples/inputs/connector_name.adoc[tag=advanced]
+include::connect:components:partial$examples/inputs/connector_name.adoc[tag=advanced]
 ====
 
-include::redpanda-connect:components:partial$fields/inputs/connector_name.adoc[]
+include::connect:components:partial$fields/inputs/connector_name.adoc[]
 
 // end::single-source[]
 ```
@@ -517,12 +517,12 @@ _No changes in this release_
 
 **For connectors in pages:**
 \```asciidoc
-include::redpanda-connect:components:page$type/name.adoc[tag=single-source]
+include::connect:components:page$type/name.adoc[tag=single-source]
 \```
 
 **For cloud-only connectors (in partials):**
 \```asciidoc
-include::redpanda-connect:components:partial$components/cloud-only/type/name.adoc[tag=single-source]
+include::connect:components:partial$components/cloud-only/type/name.adoc[tag=single-source]
 \```
 
 ### 🔧 Cgo Requirements

package/tools/redpanda-connect/helpers/renderConnectFields.js

@@ -79,7 +79,7 @@ module.exports = function renderConnectFields(children, prefix = '') {
       block += `${desc}\n\n`;
     }
     if (child.is_secret) {
-      block += `include::redpanda-connect:components:partial$secret_warning.adoc[]\n\n`;
+      block += `include::connect:components:partial$secret_warning.adoc[]\n\n`;
     }
     if (child.version) {
       block += `ifndef::env-cloud[]\nRequires version ${child.version} or later.\nendif::[]\n\n`;

package/tools/redpanda-connect/pr-summary-formatter.js

@@ -101,12 +101,12 @@ function renderBloblangChanges(data, includeVersion = false) {
   lines.push('');
   lines.push('For methods, find the appropriate category section in `methods.adoc` and add:');
   lines.push('```asciidoc');
-  lines.push('include::redpanda-connect:partial$bloblang-methods/method_name.adoc[leveloffset=+2]');
+  lines.push('include::connect:partial$bloblang-methods/method_name.adoc[leveloffset=+2]');
   lines.push('```');
   lines.push('');
   lines.push('For functions, add to the Functions section in `functions.adoc`:');
   lines.push('```asciidoc');
-  lines.push('include::redpanda-connect:partial$bloblang-functions/function_name.adoc[leveloffset=+2]');
+  lines.push('include::connect:partial$bloblang-functions/function_name.adoc[leveloffset=+2]');
   lines.push('```');
   lines.push('');
   lines.push('**Note:** Partials are auto-generated. Includes must be added manually in alphabetical order within their section.');
@@ -700,7 +700,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
           lines.push('```asciidoc');
           lines.push('= Connector Name');
           lines.push('');
-          lines.push('include::redpanda-connect:components:page$type/connector-name.adoc[tag=single-source]');
+          lines.push('include::connect:components:page$type/connector-name.adoc[tag=single-source]');
           lines.push('```');
           lines.push('');
         }
@@ -710,7 +710,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
           lines.push('```asciidoc');
           lines.push('= Connector Name');
           lines.push('');
-          lines.push('include::redpanda-connect:components:partial$components/cloud-only/type/connector-name.adoc[tag=single-source]');
+          lines.push('include::connect:components:partial$components/cloud-only/type/connector-name.adoc[tag=single-source]');
           lines.push('```');
           lines.push('');
         }