@redpanda-data/docs-extensions-and-macros 5.2.1 → 5.2.3

package/bin/doc-tools.js

@@ -26,6 +26,7 @@ const {
   diffDirs,
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
+  updatePropertiesJsonWithVersion,
   cleanupOldDiffs
 } = require('../cli-utils/diff-utils')
 
@@ -1002,6 +1003,12 @@ automation
 
           if (overridesPath && fs.existsSync(overridesPath)) {
             updatePropertyOverridesWithVersion(overridesPath, diffData, newTag)
+            // The overrides were baked into the extracted JSON during Phase 1,
+            // before the stamp above existed. Stamp the JSON too, so the
+            // AsciiDoc generated in Phase 3 shows "Introduced in" for
+            // properties new in this release instead of one release late.
+            const extractedJsonPath = path.resolve(outputDir, 'attachments', `redpanda-properties-${newTag}.json`)
+            updatePropertiesJsonWithVersion(extractedJsonPath, diffData, newTag)
           }
         }
       } catch (err) {

package/cli-utils/diff-utils.js

@@ -193,6 +193,88 @@ function updatePropertyOverridesWithVersion (overridesPath, diffData, newTag) {
   }
 }
 
+/**
+ * Stamp version information for new properties directly into an extracted
+ * properties JSON file (redpanda-properties-<tag>.json).
+ *
+ * Overrides are baked into this JSON during extraction, which happens before
+ * updatePropertyOverridesWithVersion stamps new properties into the overrides
+ * file — so without this step the AsciiDoc rendered from the JSON misses the
+ * "Introduced in" line for properties added in the release being generated
+ * (it would only appear on the next release's run).
+ *
+ * @param {string} jsonPath - Path to the extracted properties JSON file
+ * @param {object} diffData - Diff data from property comparison
+ * @param {string} newTag - Version tag for new properties (e.g., "v26.1.13")
+ */
+function updatePropertiesJsonWithVersion (jsonPath, diffData, newTag) {
+  try {
+    const newProperties = diffData.details?.newProperties || []
+    if (newProperties.length === 0) return
+    if (!fs.existsSync(jsonPath)) {
+      console.warn(`Warning: Cannot stamp versions: ${jsonPath} does not exist`)
+      return
+    }
+
+    // The stamp is a textual insertion, NOT a parse/re-serialize round-trip:
+    // JSON.stringify would corrupt values JavaScript numbers cannot represent
+    // (uint64 maxima like 18446744073709551615) and reformat floats (0.0 → 0)
+    // throughout the Python-generated file.
+    let raw = fs.readFileSync(jsonPath, 'utf8')
+    const indentUnit = (raw.match(/^([ \t]+)"/m) || [null, '    '])[1]
+
+    let stampedCount = 0
+    newProperties.forEach(prop => {
+      const updated = insertVersionIntoRawJson(raw, prop.name, newTag, indentUnit)
+      if (updated) {
+        raw = updated
+        stampedCount++
+      }
+    })
+
+    if (stampedCount > 0) {
+      JSON.parse(raw) // validate the surgical edits before touching the file
+      fs.writeFileSync(jsonPath, raw, 'utf8')
+      console.log(`Done: Stamped "Introduced in ${newTag}" on ${stampedCount} new ${stampedCount === 1 ? 'property' : 'properties'} in ${path.basename(jsonPath)}`)
+    }
+  } catch (error) {
+    console.error(`Warning: Failed to stamp versions into properties JSON: ${error.message}`)
+  }
+}
+
+/**
+ * Insert a `"version": "<newTag>",` field at the top of one property's object
+ * in the raw JSON text, leaving every other byte untouched.
+ *
+ * @param {string} raw - Full JSON file content
+ * @param {string} propName - Property key to stamp
+ * @param {string} newTag - Version tag to insert
+ * @param {string} indentUnit - One level of the file's indentation
+ * @returns {string|null} Updated content, or null when the property was not
+ *   found or already carries a version field.
+ */
+function insertVersionIntoRawJson (raw, propName, newTag, indentUnit) {
+  // Anchor the search to the top-level "properties" section when present, so
+  // an identically named key elsewhere (e.g. under "definitions") is not hit.
+  const sectionMatch = raw.match(new RegExp(`^${indentUnit}"properties": \\{`, 'm'))
+  const searchFrom = sectionMatch ? raw.indexOf(sectionMatch[0]) : 0
+
+  const escapedName = propName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const keyMatch = new RegExp(`^([ \t]+)"${escapedName}": \\{[ \t]*$`, 'm').exec(raw.slice(searchFrom))
+  if (!keyMatch) return null
+
+  const keyIndent = keyMatch[1]
+  const objStart = searchFrom + keyMatch.index + keyMatch[0].length
+
+  // Skip when the object already has a version field (scan up to its closing brace).
+  const close = new RegExp(`^${keyIndent}\\}`, 'm').exec(raw.slice(objStart))
+  const objBody = raw.slice(objStart, close ? objStart + close.index : raw.length)
+  if (new RegExp(`^${keyIndent}${indentUnit}"version":`, 'm').test(objBody)) return null
+
+  const insertion = `\n${keyIndent}${indentUnit}"version": ${JSON.stringify(newTag)},`
+  return raw.slice(0, objStart) + insertion + raw.slice(objStart)
+}
+
 /**
  * Create a unified diff patch between two directories and clean them up.
  *
@@ -269,5 +351,6 @@ module.exports = {
   cleanupOldDiffs,
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
+  updatePropertiesJsonWithVersion,
   diffDirs
 }

package/extensions/generate-rp-connect-info.js

@@ -30,11 +30,25 @@ module.exports.register = function ({ config }) {
     return require('../cli-utils/octokit-client')
   }
 
+  // Translated CSV rows, kept for the documentsConverted hook below
+  let translatedRows = null
+
   // Use 'on' and return the promise so Antora waits for async completion
   this.on('contentClassified', ({ contentCatalog }) => {
     return processContent(contentCatalog)
   })
 
+  // Set sticky-bar page attributes (type context switcher and availability badges) so the UI
+  // templates (article.hbs) render them server-side, with no flash of client-side rearranging.
+  // This must run on documentsConverted: Antora extracts page attributes for UI templates in a
+  // header-only parse with Asciidoctor extensions disabled, so these attributes cannot be set
+  // from the component_type_dropdown macro during conversion. Mutating page.asciidoc.attributes
+  // after conversion is the supported way to feed computed attributes to UI templates.
+  this.on('documentsConverted', ({ contentCatalog }) => {
+    if (!translatedRows) return
+    setStickyBarPageAttributes(contentCatalog, translatedRows, logger)
+  })
+
   async function processContent (contentCatalog) {
     const redpandaConnect = contentCatalog.getComponents().find(component => component.name === 'connect')
     const redpandaCloud = contentCatalog.getComponents().find(component => component.name === 'cloud-data-platform')
@@ -56,6 +70,7 @@ module.exports.register = function ({ config }) {
       const parsedData = Papa.parse(csvData, { header: true, skipEmptyLines: true })
       const enrichedData = translateCsvData(parsedData, pages, logger)
       parsedData.data = enrichedData
+      translatedRows = enrichedData
 
       // Set csvData on all relevant components
       const componentsToEnrich = [redpandaConnect, redpandaCloud, preview].filter(Boolean)
@@ -343,4 +358,83 @@ module.exports.register = function ({ config }) {
 
     return csvCommercialNames
   }
+
+  /**
+   * Sets sticky-bar metadata attributes on connector pages after conversion, so the UI templates
+   * (article.hbs and the context-switcher partial) render the Type dropdown and availability
+   * badges server-side:
+   * - page-context-switcher: Type dropdown entries (when the connector has multiple types)
+   * - page-cloud-available + page-cloud-available-url: on Self-Managed pages with a Cloud variant
+   * - page-self-managed-available + page-self-managed-available-url: on Cloud pages with a
+   *   Self-Managed variant
+   * - page-self-managed-only: on Self-Managed pages with no Cloud variant
+   */
+  function setStickyBarPageAttributes (contentCatalog, rows, logger) {
+    const pagesByUrl = new Map()
+    contentCatalog.getPages((page) => page.out && page.pub && page.asciidoc).forEach((page) => {
+      pagesByUrl.set(page.pub.url, page)
+    })
+
+    // Group CSV rows by connector name; each row is one type (input, output, and so on)
+    const rowsByConnector = new Map()
+    for (const row of rows) {
+      const connector = (row.connector || '').trim().toLowerCase()
+      if (!connector) continue
+      if (!rowsByConnector.has(connector)) rowsByConnector.set(connector, [])
+      rowsByConnector.get(connector).push(row)
+    }
+
+    let decoratedCount = 0
+    for (const connectorRows of rowsByConnector.values()) {
+      const isCloudSupported = connectorRows.some((row) => row.is_cloud_supported === 'y')
+      for (const row of connectorRows) {
+        // Self-Managed (Connect) variant of this connector page
+        const connectPage = row.redpandaConnectUrl && pagesByUrl.get(row.redpandaConnectUrl)
+        if (connectPage) {
+          const attrs = connectPage.asciidoc.attributes
+          if (connectorRows.length > 1) {
+            attrs['page-context-switcher'] = buildContextSwitcher(connectorRows, row, 'connect')
+          }
+          if (isCloudSupported && row.redpandaCloudUrl) {
+            attrs['page-cloud-available'] = 'true'
+            attrs['page-cloud-available-url'] = row.redpandaCloudUrl
+          } else if (!isCloudSupported) {
+            attrs['page-self-managed-only'] = 'true'
+          }
+          decoratedCount++
+        }
+        // Cloud variant of this connector page
+        const cloudPage = row.redpandaCloudUrl && pagesByUrl.get(row.redpandaCloudUrl)
+        if (cloudPage) {
+          const attrs = cloudPage.asciidoc.attributes
+          if (connectorRows.length > 1) {
+            attrs['page-context-switcher'] = buildContextSwitcher(connectorRows, row, 'cloud')
+          }
+          if (row.redpandaConnectUrl) {
+            attrs['page-self-managed-available'] = 'true'
+            attrs['page-self-managed-available-url'] = row.redpandaConnectUrl
+          }
+          decoratedCount++
+        }
+      }
+    }
+    logger.info(`Set sticky-bar metadata attributes on ${decoratedCount} connector pages`)
+  }
+
+  /**
+   * Builds the page-context-switcher JSON: one Type dropdown entry per connector type, linking to
+   * that type's page in the current site variant. The current page's type is listed first.
+   */
+  function buildContextSwitcher (connectorRows, currentRow, variant) {
+    const capitalize = (value) => value.charAt(0).toUpperCase() + value.slice(1)
+    const orderedRows = [currentRow, ...connectorRows.filter((row) => row !== currentRow)]
+    const data = {}
+    for (const row of orderedRows) {
+      const link = (variant === 'cloud' && row.redpandaCloudUrl) || row.redpandaConnectUrl
+      if (!link) continue
+      const type = row.type.trim()
+      data[type.toLowerCase()] = { name: capitalize(type), to: link }
+    }
+    return JSON.stringify(data)
+  }
 }

package/macros/rp-connect-components.js

@@ -1053,36 +1053,6 @@ module.exports.register = function (registry, context) {
             </div>
           </div>`);
       }
-      // Process types and metadata from CSV
-      const types = componentRows.map(row => ({
-        type: row.type.trim(),
-        support: row.support_level.trim(),
-        isCloudSupported: row.is_cloud_supported === 'y',
-        redpandaConnectUrl: row.redpandaConnectUrl,
-        redpandaCloudUrl: row.redpandaCloudUrl
-      }));
-      // Move the current page's type to the first position in the dropdown
-      const sortedTypes = [...types];
-      const currentTypeIndex = sortedTypes.findIndex(typeObj => typeObj.type === type);
-      if (currentTypeIndex !== -1) {
-        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') {
@@ -1092,121 +1062,23 @@ module.exports.register = function (registry, context) {
             <p><strong>License</strong>: This component requires an <a href="https://docs.redpanda.com/redpanda-connect/get-started/licensing/" target="_blank">enterprise license</a>. You can either <a href="https://www.redpanda.com/upgrade" target="_blank">upgrade to an Enterprise Edition license</a>, or <a href="http://redpanda.com/try-enterprise" target="_blank" rel="noopener">generate a trial license key</a> that's valid for 30 days.</p>`;
         }
       }
-      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) {
-        const availableInLinks = [];
-
-        // Check if the component is Cloud and apply the `current-version` class
-        if (sortedTypes[0].redpandaCloudUrl) {
-          if (component === 'Cloud') {
-            availableInLinks.push('<span title="You are viewing the Cloud version of this component" class="current-version">Cloud</span>'); // Highlight the current version
-          } else {
-            availableInLinks.push(`<a title="View the Cloud version of this component" href="${sortedTypes[0].redpandaCloudUrl}">Cloud</a>`);
-          }
-        }
-
-        // Check if the component is Connect and apply the `current-version` class
-        if (sortedTypes[0].redpandaConnectUrl) {
-          if (component === 'Connect') {
-            availableInLinks.push('<span title="You are viewing the Self-Managed version of this component" class="current-version">Self-Managed</span>'); // Highlight the current version
-          } else {
-            availableInLinks.push(`<a title="View the Self-Managed version of this component" href="${sortedTypes[0].redpandaConnectUrl}">Self-Managed</a>`);
-          }
-        }
-        availableInInfo = `<p><strong>Available in:</strong> ${availableInLinks.join(', ')}</p>`;
-      } else {
-        availableInInfo = `<p><strong>Available in:</strong> <span title="You are viewing the Self-Managed version of this component" class="current-version">Self-Managed</span></p>`;
-      }
-      // Build the dropdown for types with links depending on the current component
-      let typeDropdown = '';
-      if (sortedTypes.length > 1) {
-        const dropdownOptions = sortedTypes.map(typeObj => {
-          const link = (component === 'Cloud' && typeObj.redpandaCloudUrl) || typeObj.redpandaConnectUrl;
-          return `<a href="${link}" class="dropdown-option" role="menuitem" tabindex="-1">${capitalize(typeObj.type)}</a>`;
-        }).join('');
-        typeDropdown = `
-          <div class="dropdown-wrapper">
-            <p class="type-dropdown-container"><strong>Type:</strong>
-              <button type="button" class="dropdown-toggle" id="componentTypeDropdownToggle" onclick="toggleComponentTypeDropdown()" aria-expanded="false" aria-haspopup="true" aria-controls="componentTypeDropdownMenu">
-                <span class="dropdown-text">${capitalize(sortedTypes[0].type)}</span>
-                <span class="dropdown-arrow">▼</span>
-              </button>
-              <div class="dropdown-menu" id="componentTypeDropdownMenu" role="menu" aria-labelledby="componentTypeDropdownToggle">
-                ${dropdownOptions}
-              </div>
-            </p>
-          </div>`;
+      // The Type dropdown and availability info are rendered server-side in the sticky bar by the
+      // UI (article.hbs) from page attributes (page-context-switcher, page-cloud-available, and
+      // so on). Those attributes cannot be set from this macro: Antora extracts page attributes
+      // for UI templates in a header-only parse that runs before conversion with Asciidoctor
+      // extensions disabled, so anything set here never reaches the templates. The
+      // generate-rp-connect-info extension sets them on page.asciidoc.attributes on the
+      // documentsConverted event instead. Only the license notice belongs in the page body,
+      // where it must stay visible.
+      if (!enterpriseLicenseInfo) {
+        return self.createBlock(parent, 'pass', '');
       }
-      // Return the metadata block with consistent layout
       return self.createBlock(parent, 'pass', `
         <div class="metadata-block">
           <div class="metadata-content">
-          ${typeDropdown}
-          ${availableInInfo}
           ${enterpriseLicenseInfo}
           </div>
-        </div>
-        <script>
-          // Define global dropdown functions directly (shared between macros)
-          if (!window.toggleComponentTypeDropdown) {
-            window.toggleComponentTypeDropdown = function() {
-              const toggle = document.getElementById('componentTypeDropdownToggle');
-              const menu = document.getElementById('componentTypeDropdownMenu');
-              
-              if (!toggle || !menu) return;
-              
-              const isOpen = menu.classList.contains('show');
-              
-              // Close all other dropdowns first (including filter dropdowns)
-              document.querySelectorAll('.dropdown-checkbox-menu.show, .dropdown-menu.show').forEach(dropdown => {
-                if (dropdown !== menu) {
-                  dropdown.classList.remove('show');
-                  const otherToggle = dropdown.parentNode.querySelector('.dropdown-checkbox-toggle, .dropdown-toggle');
-                  if (otherToggle) {
-                    otherToggle.classList.remove('open');
-                    otherToggle.setAttribute('aria-expanded', 'false');
-                  }
-                }
-              });
-              
-              // Toggle current dropdown
-              if (isOpen) {
-                menu.classList.remove('show');
-                toggle.classList.remove('open');
-                toggle.setAttribute('aria-expanded', 'false');
-              } else {
-                menu.classList.add('show');
-                toggle.classList.add('open');
-                toggle.setAttribute('aria-expanded', 'true');
-                // Focus first option
-                const firstOption = menu.querySelector('.dropdown-option');
-                if (firstOption) firstOption.focus();
-              }
-            };
-          }
-        </script>`);
+        </div>`);
     });
   });
 

package/package.json

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

package/tools/redpanda-connect/metadata-utils.js

@@ -14,10 +14,17 @@
  */
 
 const METADATA_HEADING = /^==\s+Metadata\s*$/;
-const LEVEL2_HEADING = /^==\s+\S/;
 // AsciiDoc listing/literal block delimiter (`----`, possibly longer). Lines
 // inside such blocks must not be treated as headings.
 const BLOCK_DELIMITER = /^-{4,}$/;
+// The metadata block ends at the next structural element. Besides the next
+// level-2 heading, this also covers page-level constructs that follow the
+// section when locateMetadata runs against a full reference page (not just a
+// connector description): Antora include directives (for example the fields or
+// examples partials) and single-source tag comments. Without these, a metadata
+// section that is the last heading on a page would run to end-of-string and
+// swallow the trailing `include::...partial$fields[]` and `// end::single-source[]`.
+const SECTION_END = /^(?:==\s+\S|include::|\/\/\s*(?:tag|end)::)/;
 
 /**
  * Locate the `== Metadata` section within a description.
@@ -38,12 +45,13 @@ function locateMetadata (description) {
   }
   if (headingLine === -1) return null;
 
-  // Find the terminating heading (next level-2 heading after the metadata one).
+  // Find the terminating element after the metadata heading: the next level-2
+  // heading, an Antora include directive, or a single-source tag comment.
   let endLine = lines.length;
   inBlock = false;
   for (let i = headingLine + 1; i < lines.length; i++) {
     if (BLOCK_DELIMITER.test(lines[i])) { inBlock = !inBlock; continue; }
-    if (!inBlock && LEVEL2_HEADING.test(lines[i])) { endLine = i; break; }
+    if (!inBlock && SECTION_END.test(lines[i])) { endLine = i; break; }
   }
 
   // Trim trailing blank lines inside the section so the block ends cleanly.

package/tools/redpanda-connect/migrate-metadata-to-partials.js

@@ -29,6 +29,21 @@ const PARTIAL_BANNER =
 const PAGES_ROOT = path.resolve(process.cwd(), 'modules/components/pages');
 const PARTIALS_ROOT = path.resolve(process.cwd(), 'modules/components/partials/metadata');
 
+/**
+ * True when a generated metadata partial carries no actual metadata — either it
+ * is only the autogeneration banner / comments, or it has no `== Metadata`
+ * heading. The generator writes such a partial when the connector's upstream
+ * description has no `== Metadata` section.
+ * @param {string} partial
+ * @returns {boolean}
+ */
+function isEmptyMetadataPartial (partial) {
+  // Reuse the same literal-block-aware parser used for extraction, so a
+  // `== Metadata` line inside a `----` code block (for example an example that
+  // literally contains that text) is not mistaken for a real metadata section.
+  return !locateMetadata(partial);
+}
+
 /** Recursively collect .adoc files under a directory (minimatch glob). */
 function collectAdocFiles (dir) {
   if (!fs.existsSync(dir)) return [];
@@ -75,6 +90,18 @@ function migrateMetadataToPartials ({ write = false } = {}) {
     // migration works standalone but never clobbers generated content.
     const partialExists = fs.existsSync(partialPath);
 
+    // Guard against metadata loss: when the generator produced an EMPTY partial
+    // (the connector's upstream description has no == Metadata section), the
+    // page's inline block is the only real metadata. Migrating it to an include
+    // would replace live metadata with an empty partial. Skip these — the
+    // connector's upstream description must gain a == Metadata section before
+    // the page can be migrated.
+    if (partialExists && isEmptyMetadataPartial(fs.readFileSync(partialPath, 'utf8'))) {
+      console.log(`SKIP (generated partial is empty; keeping inline metadata): ${typeDir}/${name}`);
+      skipped++;
+      continue;
+    }
+
     console.log(`${write ? 'MIGRATE' : 'WOULD MIGRATE'}: ${typeDir}/${name}`);
     console.log(`  -> partial: ${path.relative(process.cwd(), partialPath)}${partialExists ? ' (exists, kept)' : ' (seeded from page)'}`);
 
@@ -94,7 +121,7 @@ function migrateMetadataToPartials ({ write = false } = {}) {
   return { migrated, skipped };
 }
 
-module.exports = { migrateMetadataToPartials };
+module.exports = { migrateMetadataToPartials, isEmptyMetadataPartial };
 
 // Allow direct execution for local development; the supported entry point is
 // `npx doc-tools generate migrate-rpcn-metadata`.