@redpanda-data/docs-extensions-and-macros 4.6.9 → 4.6.11

package/README.adoc

@@ -739,6 +739,74 @@ antora:
     unlistedPagesHeading: 'Additional Resources'
 ```
 
+=== Process context switcher
+
+This extension processes the `page-context-switcher` attribute to enable cross-version navigation widgets in documentation pages. It automatically replaces "current" references with full resource IDs and injects the context switcher configuration to all referenced target pages, ensuring bidirectional navigation works correctly.
+
+The extension finds pages with the `page-context-switcher` attribute, parses the JSON configuration, and:
+
+1. Replaces any "current" values with the full resource ID of the current page
+2. Finds all target pages referenced in the switcher configuration  
+3. Injects the same context switcher attribute to target pages (with appropriate resource ID mappings)
+4. Builds resource IDs in the format: `version@component:module:relative-path`
+
+This enables UI components to render version switchers that work across different versions of the same content.
+
+==== Environment variables
+
+This extension does not require any environment variables.
+
+==== Configuration options  
+
+This extension does not require any configuration options.
+
+==== Registration
+
+```yaml
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/process-context-switcher'
+```
+
+==== Usage
+
+Add the `page-context-switcher` attribute to any page where you want cross-version navigation:
+
+```asciidoc
+:page-context-switcher: [{"name": "Version 2.x", "to": "24.3@ROOT:console:config/security/authentication.adoc" },{"name": "Version 3.x", "to": "current" }]
+```
+
+==== Processed output
+
+After processing, the "current" reference is replaced with the full resource ID:
+
+```json
+[
+  {"name": "Version 2.x", "to": "24.3@ROOT:console:config/security/authentication.adoc"},
+  {"name": "Version 3.x", "to": "current@ROOT:console:config/security/authentication.adoc"}
+]
+```
+
+The target page (`24.3@ROOT:console:config/security/authentication.adoc`) will also receive the same context switcher configuration with appropriate resource ID mappings.
+
+==== UI integration
+
+The processed attribute can be used in Handlebars templates:
+
+```html
+<div class="context-switcher">
+  {{#each (obj page.attributes.page-context-switcher)}}
+    <a
+      id="{{{this.name}}}"
+      href="{{{relativize (resolve-resource this.to)}}}"
+      class="context-link {{#if (eq @root.page.url (resolve-resource this.to))}}active{{/if}}"
+    >
+      <button type="button">{{{this.name}}}</button>
+    </a>
+  {{/each}}
+</div>
+```
+
 == Asciidoc Extensions
 
 This section documents the Asciidoc extensions that are provided by this library and how to configure them.

package/bin/doc-tools.js

@@ -273,13 +273,14 @@ After installation, verify with:
 
   // Check for C++ standard library headers (critical for tree-sitter compilation)
   let tempDir = null;
+  let compileCmd = null;
   try {
     const testProgram = '#include <functional>\nint main() { return 0; }';
     tempDir = require('fs').mkdtempSync(require('path').join(require('os').tmpdir(), 'cpp-test-'));
     const tempFile = require('path').join(tempDir, 'test.cpp');
     require('fs').writeFileSync(tempFile, testProgram);
 
-    const compileCmd = cppCompiler === 'gcc' ? 'gcc' : 'clang++';
+    compileCmd = cppCompiler === 'gcc' ? 'gcc' : 'clang++';
     execSync(`${compileCmd} -x c++ -fsyntax-only "${tempFile}"`, { stdio: 'ignore' });
     require('fs').rmSync(tempDir, { recursive: true, force: true });
   } catch {
@@ -293,22 +294,22 @@ After installation, verify with:
     }
     fail(`C++ standard library headers are missing or incomplete.
 
-This error typically means:
-1. No C++ compiler is installed, OR
-2. Xcode Command Line Tools are missing/incomplete
+1. **Test if the issue exists**:
+   echo '#include <functional>' | ${compileCmd} -x c++ -fsyntax-only -
 
-To fix this on macOS:
-1. Install Xcode Command Line Tools:
-   xcode-select --install
-
-2. If already installed, reset the developer path:
+2. **If the test fails, try these fixes in order**:
+   **Fix 1**: Reset developer path
    sudo xcode-select --reset
 
-3. For Xcode users, ensure correct path:
-   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+   **Fix 2**: Force reinstall Command Line Tools
+   sudo rm -rf /Library/Developer/CommandLineTools
+   xcode-select --install
+
+   Complete the GUI installation dialog that appears.
 
-4. Verify the fix:
-   echo '#include <functional>' | \${cppCompiler || 'clang++'} -x c++ -fsyntax-only -
+3. **Verify the fix**:
+   echo '#include <functional>' | ${compileCmd} -x c++ -fsyntax-only -
+   If successful, you should see no output and the command should exit with code 0.
 `);
   }
 }

package/extensions/find-related-labs.js

@@ -31,7 +31,7 @@ function findRelated(labPage, sourceCategoryList, sourceDeploymentType, logger)
   const targetCategoryList = pageCategories.split(',').map(c => c.trim());
   const targetDeploymentType = getDeploymentType(targetAttributes)
   const categoryMatch = hasMatchingCategory(sourceCategoryList, targetCategoryList)
-  if (categoryMatch && (!targetDeploymentType ||sourceDeploymentType === targetDeploymentType || (targetDeploymentType === 'Docker' && !sourceDeploymentType))) {
+  if (categoryMatch && isCompatibleDeployment(sourceDeploymentType, targetDeploymentType)) {
     return {
       title: labPage.asciidoc.doctitle,
       url: labPage.pub.url,
@@ -51,4 +51,21 @@ function getDeploymentType (attributes) {
 
 function hasMatchingCategory (sourcePageCategories, targetPageCategories) {
   return sourcePageCategories.every((category) => targetPageCategories.includes(category))
+}
+
+function isCompatibleDeployment (sourceDeploymentType, targetDeploymentType) {
+  // If no target deployment type specified, it's compatible with everything
+  if (!targetDeploymentType) return true
+
+  // Cloud pages show only cloud labs
+  if (sourceDeploymentType === 'Redpanda Cloud') {
+    return targetDeploymentType === 'Redpanda Cloud'
+  }
+
+  // All other cases (Kubernetes, Docker, Linux, or no deployment type) show Docker and Kubernetes
+  if (targetDeploymentType === 'Docker' || targetDeploymentType === 'Kubernetes') {
+    return true
+  }
+
+  return false
 }

package/extensions/process-context-switcher.js

@@ -0,0 +1,236 @@
+/* Example use in the playbook
+* antora:
+    extensions:
+ *    - require: ./extensions/process-context-switcher.js
+ *
+ * This extension processes the `page-context-switcher` attribute and:
+ * 1. Replaces "current" references with the full resource ID of the current page
+ * 2. Injects context switchers into target pages with proper bidirectional linking
+ * 3. Automatically adds the current page's version to resource IDs that don't specify one
+ *
+ * Example context switcher attribute:
+ * :page-context-switcher: [{"name": "Version 2.x", "to": "ROOT:console:config/security/authentication.adoc"}, {"name": "Version 3.x", "to": "current"}]
+ *
+ * Note: You can omit the version from resource IDs - the extension will automatically
+ * use the current page's version. So "ROOT:console:file.adoc" becomes "current@ROOT:console:file.adoc"
+*/
+
+'use strict';
+
+module.exports.register = function ({ config }) {
+  const logger = this.getLogger('context-switcher-extension');
+
+  this.on('documentsConverted', async ({ contentCatalog }) => {
+    // Find all pages with context-switcher attribute
+    const pages = contentCatalog.findBy({ family: 'page' });
+    const pagesToProcess = pages.filter(page =>
+      page.asciidoc.attributes['page-context-switcher']
+    );
+
+    if (pagesToProcess.length === 0) {
+      logger.debug('No pages found with page-context-switcher attribute');
+      return;
+    }
+
+    logger.info(`Processing context-switcher attribute for ${pagesToProcess.length} pages`);
+
+    // Process each page with context-switcher
+    for (const page of pagesToProcess) {
+      processContextSwitcher(page, contentCatalog, logger);
+    }
+  });
+
+  /**
+   * Process the context-switcher attribute for a page
+   * @param {Object} page - The page object
+   * @param {Object} contentCatalog - The content catalog
+   * @param {Object} logger - Logger instance
+   */
+  function processContextSwitcher(page, contentCatalog, logger) {
+    const contextSwitcherAttr = page.asciidoc.attributes['page-context-switcher'];
+
+    try {
+      // Parse the JSON attribute
+      const contextSwitcher = JSON.parse(contextSwitcherAttr);
+
+      if (!Array.isArray(contextSwitcher)) {
+        logger.warn(`Invalid context-switcher format in ${page.src.path}: expected array`);
+        return;
+      }
+
+      // Get current page's full resource ID
+      const currentResourceId = buildResourceId(page);
+      logger.debug(`Processing context-switcher for page: ${currentResourceId}`);
+
+      // Make a copy for processing target pages (before modifying "current")
+      const originalContextSwitcher = JSON.parse(JSON.stringify(contextSwitcher));
+
+      // Track if we made any changes
+      let hasChanges = false;
+
+      // Process each context switcher item
+      for (let item of contextSwitcher) {
+        if (item.to === 'current') {
+          item.to = currentResourceId;
+          hasChanges = true;
+          logger.debug(`Replaced 'current' with '${currentResourceId}' in context-switcher`);
+        } else if (item.to !== currentResourceId) {
+          // For non-current items, find and update the target page
+          const targetPage = findPageByResourceId(item.to, contentCatalog, page);
+          if (targetPage) {
+            injectContextSwitcherToTargetPage(targetPage, originalContextSwitcher, currentResourceId, logger);
+          } else {
+            logger.warn(`Target page not found for resource ID: '${item.to}'. Check that the component, module, and path exist. Enable debug logging to see available pages.`);
+          }
+        }
+      }
+
+      // Update the current page's attribute if we made changes
+      if (hasChanges) {
+        page.asciidoc.attributes['page-context-switcher'] = JSON.stringify(contextSwitcher);
+      }
+
+    } catch (error) {
+      logger.error(`Error parsing context-switcher attribute in ${page.src.path}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Build a full resource ID for a page (component:module:relative-path)
+   * @param {Object} page - The page object
+   * @returns {string} The full resource ID
+   */
+  function buildResourceId(page) {
+    const component = page.src.component;
+    const version = page.src.version;
+    const module = page.src.module || 'ROOT';
+    const relativePath = page.src.relative;
+
+    // Format: version@component:module:relative-path
+    return `${version}@${component}:${module}:${relativePath}`;
+  }
+
+  /**
+   * Normalize a resource ID by adding the current page's version if missing
+   * @param {string} resourceId - The resource ID to normalize
+   * @param {Object} currentPage - The current page (for context)
+   * @returns {string} The normalized resource ID
+   */
+  function normalizeResourceId(resourceId, currentPage) {
+    // Sanitize input to avoid syntax errors
+    if (!resourceId || typeof resourceId !== 'string') {
+      throw new Error('Resource ID must be a non-empty string');
+    }
+
+    if (!currentPage || !currentPage.src || !currentPage.src.version) {
+      throw new Error('Current page must have a valid src.version property');
+    }
+
+    // Trim whitespace and remove any dangerous characters
+    const sanitizedResourceId = resourceId.trim();
+    if (!sanitizedResourceId) {
+      throw new Error('Resource ID cannot be empty or whitespace-only');
+    }
+
+    // Validate basic resource ID format (component:module:path or version@component:module:path)
+    if (!/^([^@]+@)?[^:]+:[^:]+:.+$/.test(sanitizedResourceId)) {
+      throw new Error(`Invalid resource ID format: '${sanitizedResourceId}'. Expected format: [version@]component:module:path`);
+    }
+
+    // If the resource ID already contains a version (has @), return as-is
+    if (sanitizedResourceId.includes('@')) {
+      return sanitizedResourceId;
+    }
+
+    // Add the current page's version to the resource ID
+    const currentVersion = currentPage.src.version;
+    return `${currentVersion}@${sanitizedResourceId}`;
+  }
+
+  /**
+   * Find a page by its resource ID using Antora's built-in resolution
+   * @param {string} resourceId - The resource ID to find
+   * @param {Object} contentCatalog - The content catalog
+   * @param {Object} currentPage - The current page (for context)
+   * @returns {Object|null} The found page or null
+   */
+  function findPageByResourceId(resourceId, contentCatalog, currentPage) {
+    try {
+      // Normalize the resource ID by adding version if missing
+      const normalizedResourceId = normalizeResourceId(resourceId, currentPage);
+
+      if (normalizedResourceId !== resourceId) {
+        logger.debug(`Normalized resource ID '${resourceId}' to '${normalizedResourceId}' using current page version`);
+      }
+
+      try {
+        // Use Antora's built-in resource resolution
+        const resource = contentCatalog.resolveResource(normalizedResourceId, currentPage.src);
+
+        if (resource) {
+          logger.debug(`Resolved resource ID '${normalizedResourceId}' to: ${buildResourceId(resource)}`);
+          return resource;
+        } else {
+          logger.warn(`Could not resolve resource ID: '${normalizedResourceId}'. Check that the component, module, and path exist.`);
+
+          // Provide some debugging help by showing available pages in the current component
+          const currentComponentPages = contentCatalog.findBy({
+            family: 'page',
+            component: currentPage.src.component
+          }).slice(0, 10);
+
+          logger.debug(`Available pages in current component '${currentPage.src.component}' (first 10):`,
+            currentComponentPages.map(p => `${p.src.version}@${p.src.component}:${p.src.module || 'ROOT'}:${p.src.relative}`));
+
+          return null;
+        }
+      } catch (error) {
+        logger.debug(`Error resolving resource ID '${normalizedResourceId}': ${error.message}`);
+        return null;
+      }
+    } catch (error) {
+      // Handle normalization errors (invalid resource ID format)
+      logger.warn(`Invalid resource ID '${resourceId}': ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Inject context-switcher attribute to target page
+   * @param {Object} targetPage - The target page to inject to
+   * @param {Array} contextSwitcher - The context switcher configuration
+   * @param {string} currentPageResourceId - The current page's resource ID
+   * @param {Object} logger - Logger instance
+   */
+  function injectContextSwitcherToTargetPage(targetPage, contextSwitcher, currentPageResourceId, logger) {
+    // Check if target page already has context-switcher attribute
+    if (targetPage.asciidoc.attributes['page-context-switcher']) {
+      logger.warn(`Target page ${buildResourceId(targetPage)} already has context-switcher attribute. Skipping injection to avoid overwriting existing configuration: ${targetPage.asciidoc.attributes['page-context-switcher']}`);
+      return;
+    }
+
+    const targetPageResourceId = buildResourceId(targetPage);
+
+    logger.debug(`Injecting context switcher to target page: ${targetPageResourceId}`);
+
+    // Create a copy of the context switcher for the target page
+    // Simply replace "current" with the original page's resource ID
+    const targetContextSwitcher = contextSwitcher.map(item => {
+      if (item.to === 'current') {
+        logger.debug(`Replacing 'current' with original page: ${currentPageResourceId}`);
+        return {
+          ...item,
+          to: currentPageResourceId
+        };
+      }
+      // All other items stay the same
+      return { ...item };
+    });
+
+    logger.debug(`Target context switcher:`, JSON.stringify(targetContextSwitcher, null, 2));
+
+    // Inject the attribute
+    targetPage.asciidoc.attributes['page-context-switcher'] = JSON.stringify(targetContextSwitcher);
+    logger.debug(`Successfully injected context-switcher to target page: ${targetPageResourceId}`);
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.6.9",
+  "version": "4.6.11",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -37,6 +37,7 @@
       "require": "./extensions/unlisted-pages.js"
     },
     "./extensions/replace-attributes-in-attachments": "./extensions/replace-attributes-in-attachments.js",
+    "./extensions/process-context-switcher": "./extensions/process-context-switcher.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",