@redpanda-data/docs-extensions-and-macros 5.2.2 → 5.2.4

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.2",
+  "version": "5.2.4",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

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

@@ -1,13 +1,15 @@
 'use strict';
 
 const { extractMetadata } = require('../metadata-utils.js');
+const { normalizeMetadataBlock } = require('../normalize-metadata.js');
 
 /**
  * Handlebars helper: return the `== Metadata` block extracted from a connector
- * description, or '' when there is none. Used by the metadata partial template.
+ * description with consistent field-list formatting, or '' when there is none.
+ * Used by the metadata partial template.
  * @param {string} description
  * @returns {string}
  */
 module.exports = function renderConnectMetadata (description) {
-  return extractMetadata(description);
+  return normalizeMetadataBlock(extractMetadata(description));
 };

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`.

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

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * Normalize the formatting of an extracted `== Metadata` block so the generated
+ * metadata partials are consistent regardless of how each connector authored
+ * its metadata section upstream.
+ *
+ * Two inconsistencies are normalized:
+ *   1. Some connectors wrap their field list in a fenced code block
+ *      (```text ... ``` or ``` ... ```) of bare names; others use an AsciiDoc
+ *      bullet list with the field name in inline code. We strip the fences
+ *      around a field list and render the fields as a plain bullet list.
+ *   2. Within a field bullet, the field name (a lowercase snake_case
+ *      identifier) is wrapped in inline code. Descriptive bullets such as
+ *      "All headers (only first values are taken)" are left as prose, and
+ *      bullets that already contain inline code are left untouched.
+ *
+ * Everything else (intro sentences, notes, `===` subheadings that legitimately
+ * group metadata by operation, non-field-list fenced blocks, and AsciiDoc
+ * `----` literal blocks) is preserved verbatim.
+ */
+
+const FENCE_OPEN = /^(\s*)(```|~~~)(.*)$/;
+const BULLET = /^(\s*[-*]\s+)(.*)$/;
+// AsciiDoc literal/listing block delimiter. Content inside `----` blocks is
+// rendered verbatim, so backticks would show up literally — such regions must
+// pass through untouched (no field-name inline-coding).
+const BLOCK_DELIMITER = /^-{4,}$/;
+// A metadata field bullet: the leading token is a lowercase snake_case
+// identifier (gcs_key, http_server_verb, header), optionally followed by a
+// parenthetical annotation (for example "(RFC3339)"), and optionally a
+// description separated by ":" or " - ". This distinguishes real field bullets
+// from descriptive ones like "All headers ..." (which start with a capital).
+// The description may itself contain inline code, so it is matched loosely.
+const FIELD_BULLET = /^([a-z][a-z0-9_]*)((?:\s*\([^)]*\))?(?:\s*(?::|-)\s.*)?)$/s;
+
+function normalizeBullet (prefix, content) {
+  // Skip only when the field name itself is already inline-coded; a backtick
+  // later in the description must not prevent coding the field name.
+  if (content.startsWith('`')) return prefix + content;
+  const m = content.match(FIELD_BULLET);
+  if (!m) return prefix + content;                     // descriptive, leave as prose
+  return `${prefix}\`${m[1]}\`${m[2]}`;                 // inline-code the field name
+}
+
+/** True when a fenced block's info string and content are a bare field list. */
+function isFieldListFence (infoString, contentLines) {
+  const info = infoString.trim();
+  if (info !== '' && info !== 'text') return false;
+  const nonBlank = contentLines.filter((l) => l.trim() !== '');
+  if (nonBlank.length === 0 || !nonBlank.every((l) => BULLET.test(l))) return false;
+  // Require at least one real field-name bullet. A fenced block of purely
+  // descriptive bullets (no snake_case field name) is not a field list, so its
+  // fences must be preserved rather than stripped.
+  return nonBlank.some((l) => {
+    const b = l.match(BULLET);
+    return b && FIELD_BULLET.test(b[2]);
+  });
+}
+
+/**
+ * @param {string} block the extracted `== Metadata` block
+ * @returns {string} the block with consistent field-list formatting
+ */
+function normalizeMetadataBlock (block) {
+  if (!block || typeof block !== 'string') return block;
+  const lines = block.split('\n');
+  const out = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    // AsciiDoc literal/listing block: pass the whole `----` … `----` region
+    // through verbatim. Field-name lines inside are rendered literally, so they
+    // must not be inline-coded (backticks would appear as visible characters).
+    if (BLOCK_DELIMITER.test(lines[i].trim())) {
+      out.push(lines[i]);
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        out.push(lines[j]);
+        if (BLOCK_DELIMITER.test(lines[j].trim())) break;
+      }
+      i = j;
+      continue;
+    }
+
+    const fence = lines[i].match(FENCE_OPEN);
+    if (fence) {
+      // Collect the fenced content up to a closing fence of the SAME marker
+      // (a ```-opened block is not closed by ~~~, and vice versa).
+      const marker = fence[2];
+      const content = [];
+      let j = i + 1;
+      let closed = false;
+      for (; j < lines.length; j++) {
+        if (lines[j].trim() === marker) { closed = true; break; }
+        content.push(lines[j]);
+      }
+      if (closed && isFieldListFence(fence[3], content)) {
+        // Drop the fences and render the fields as a normal bullet list.
+        for (const c of content) {
+          const b = c.match(BULLET);
+          out.push(b ? normalizeBullet(b[1], b[2]) : c);
+        }
+      } else {
+        // Not a field list (e.g. a YAML example) — keep verbatim.
+        out.push(lines[i]);
+        for (const c of content) out.push(c);
+        if (closed) out.push(lines[j]);
+      }
+      i = closed ? j : lines.length;
+    } else {
+      // Bare bullet outside a fence: normalize the field name too.
+      const b = lines[i].match(BULLET);
+      out.push(b ? normalizeBullet(b[1], b[2]) : lines[i]);
+    }
+  }
+
+  return out.join('\n');
+}
+
+module.exports = { normalizeMetadataBlock };