@redpanda-data/docs-extensions-and-macros 3.2.12 → 3.3.1

package/README.adoc

@@ -77,6 +77,22 @@ antora:
     index-latest-only: true
 ```
 
+=== Component category aggregator
+
+This extension maps Redpanda Connect component data into a structured format:
+
+- Maps original component names to common names.
+- Populates `connectCategoriesData` and `flatComponentsData` attributes.
+- Skips deprecated components.
+
+==== Registration Example
+
+```yaml
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/generate-rp-connect-categories'
+```
+
 === Version fetcher
 
 This extension fetches the latest release versions from GitHub.
@@ -420,6 +436,66 @@ asciidoc:
     - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
 ----
 
+=== components_by_category
+
+This macro generates a tabbed interface to display Redpanda Connect components by category.
+
+The categories are fetched from the `connectCategoriesData` that's generated in the << Component category aggregator>> extension.
+
+==== Usage
+
+```asciidoc
+components_by_category::[<type>]
+```
+
+==== Registration example
+
+```yaml
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
+```
+
+=== component_table
+
+This macro generates a searchable table of all Redpanda Connect components with filters for support and type.
+
+The types are fetched from the `flatComponentsData` that's generated in the << Component category aggregator>> extension.
+
+==== Usage
+
+```asciidoc
+component_table::[]
+```
+
+==== Registration example
+
+```yaml
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
+```
+
+=== component_type_dropdown
+
+This macro generates a dropdown of other supported types for a particular component, allowing users to switch between different types.
+
+The types are fetched from the `flatComponentsData` that's generated in the << Component category aggregator>> extension.
+
+==== Usage
+
+```asciidoc
+component_type_dropdown::[]
+```
+
+==== Registration example
+
+```yaml
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
+```
+
 == Development quickstart
 
 This section provides information on how to develop this project.

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

@@ -0,0 +1,159 @@
+'use strict';
+
+module.exports.register = function ({ config }) {
+  const logger = this.getLogger('redpanda-connect-category-aggregation-extension');
+
+  // TODO: Integrate these as attributes like common-name in the autogenerated source pages.
+  // This hardcoded map is just for launch.
+  const componentNameMap = {
+    "aws_kinesis_data_streams": "AWS Kinesis Data Streams",
+    "aws_kinesis_firehose": "AWS Kinesis Firehose",
+    "aws_kinesis": "AWS Kinesis",
+    "aws_sqs": "AWS SQS",
+    "aws_sns": "AWS SNS",
+    "azure_cosmosdb": "Azure Cosmos DB",
+    "azure_table_storage": "Azure Table Storage",
+    "gcp_bigquery": "GCP BigQuery",
+    "oracle": "Oracle",
+    "snowflake_put": "Snowflake",
+    "aws_dynamodb": "AWS DynamoDB",
+    "azure_blob_storage": "Azure Blob Storage",
+    "aws_s3": "AWS S3",
+    "cassandra": "Cassandra",
+    "gcp_cloud_storage": "GCP Cloud Storage",
+    "amqp": "AMQP",
+    "avro": "Avro",
+    "awk": "AWK",
+    "aws_lambda": "AWS Lambda",
+    "azure_queue_storage": "Azure Queue Storage",
+    "clickhouse": "ClickHouse",
+    "cockroachdb_changefeed": "CockroachDB",
+    "couchbase": "Couchbase",
+    "csv": "CSV",
+    "discord": "Discord",
+    "elasticsearch": "Elasticsearch",
+    "kafka_franz": "Franz-go",
+    "gcp_pubsub": "GCP Pub/Sub",
+    "grok": "Grok",
+    "hdfs": "HDFS",
+    "http": "HTTP",
+    "javascript": "JavaScript",
+    "jmespath": "JMESPath",
+    "json_schema": "JSON Schema",
+    "kafka": "Kafka",
+    "memcached": "Memcached",
+    "msgpack": "MessagePack",
+    "mongodb": "MongoDB",
+    "mqtt": "MQTT",
+    "mysql": "MySQL",
+    "nanomsg": "nanomsg",
+    "nats": "NATS",
+    "nsq": "NSQ",
+    "opensearch": "OpenSearch",
+    "parquet": "Parquet",
+    "postgresql": "PostgreSQL",
+    "protobuf": "Protobuf",
+    "pulsar": "Pulsar",
+    "redis": "Redis",
+    "ristretto": "Ristretto",
+    "schema_registry": "Schema Registry",
+    "sentry": "Sentry",
+    "socket": "Socket",
+    "sql": "SQL",
+    "sqlite": "SQLite",
+    "trino": "Trino",
+    "wasm": "Wasm (WebAssembly)",
+    "websocket": "WebSocket",
+    "twitter_search": "X (Twitter)",
+    "xml": "XML"
+  };
+
+  this.once('contentClassified', ({ siteCatalog, contentCatalog }) => {
+    const redpandaConnect = contentCatalog.getComponents().find(component => component.name === 'redpanda-connect');
+    if (!redpandaConnect || !redpandaConnect.latest) {
+      logger.info('Could not find the redpanda-connect component');
+      return;
+    }
+    const descriptions = redpandaConnect.latest.asciidoc.attributes.categories;
+    if (!descriptions) {
+      logger.info('No categories attribute found in redpanda-connect component');
+      return;
+    }
+
+    const connectCategoriesData = {};
+    const flatComponentsData = [];
+    const types = Object.keys(descriptions);
+
+    // Initialize connectCategoriesData for each type
+    types.forEach(type => {
+      connectCategoriesData[type] = [];
+    });
+
+    try {
+      const files = contentCatalog.findBy({ component: 'redpanda-connect', family: 'page' });
+
+      files.forEach(file => {
+        const content = file.contents.toString('utf8');
+        const categoryMatch = /:categories: (.*)/.exec(content);
+        const typeMatch = /:type: (.*)/.exec(content);
+        const statusMatch = /:status: (.*)/.exec(content);
+        const pubUrl = file.pub.url;
+        const name = file.src.stem;
+
+        if (categoryMatch && typeMatch) {
+          let categories = categoryMatch[1];
+          const fileType = typeMatch[1];
+          let status = statusMatch ? statusMatch[1] : 'Enterprise';
+          if (status === 'beta' || status === 'experimental') status = 'Community';
+          if (status === 'stable') status = 'Enterprise';
+
+          // Skip deprecated components
+          if (status === 'deprecated') return;
+
+          // Map component name to common name
+          const commonName = componentNameMap[name] || name;
+
+          // Populate connectCategoriesData
+          if (types.includes(fileType) && categories) {
+            if (typeof categories === 'string') {
+              categories = categories.replace(/[\[\]"]/g, '').split(',').map(category => category.trim());
+            }
+
+            categories.forEach(category => {
+              let categoryObj = connectCategoriesData[fileType].find(cat => cat.name === category);
+
+              if (!categoryObj) {
+                categoryObj = descriptions[fileType].find(desc => desc.name === category) || { name: category, description: "" };
+                categoryObj.items = [];
+                connectCategoriesData[fileType].push(categoryObj);
+              }
+
+              categoryObj.items.push({ name: commonName, url: pubUrl, status: status });
+            });
+          }
+
+          // Populate flatComponentsData
+          let flatItem = flatComponentsData.find(item => item.name === commonName);
+          if (flatItem) {
+            if (!flatItem.types.includes(fileType)) {
+              flatItem.types.push({ type: fileType, url: pubUrl });
+            }
+          } else {
+            flatItem = { name: commonName, originalName: name, support: status, types: [{ type: fileType, url: pubUrl }] };
+            flatComponentsData.push(flatItem);
+          }
+        }
+      });
+
+      try {
+        redpandaConnect.latest.asciidoc.attributes.connectCategoriesData = connectCategoriesData;
+        redpandaConnect.latest.asciidoc.attributes.flatComponentsData = flatComponentsData;
+        logger.info(`Added Redpanda Connect data to latest Asciidoc object: ${JSON.stringify({ connectCategoriesData, flatComponentsData }, null, 2)}`);
+      } catch (error) {
+        logger.error(`Error updating latest Asciidoc object for Redpanda Connect: ${error.message}`);
+      }
+    } catch (error) {
+      logger.error(`Error processing Redpanda Connect files: ${error.message}`);
+    }
+  });
+};

package/extensions/unlisted-pages.js

@@ -2,7 +2,7 @@ module.exports.register = function ({ config }) {
   const { addToNavigation, unlistedPagesHeading = 'Unlisted Pages' } = config
   const logger = this.getLogger('unlisted-pages-extension')
   this
-    .on('navigationBuilt', ({ contentCatalog }) => {
+    .on('navigationBuilt', ({ navigationCatalog, contentCatalog }) => {
       contentCatalog.getComponents().forEach(({ versions }) => {
         versions.forEach(({ name: component, version, navigation: nav, url: defaultUrl }) => {
           if (component === 'api') return;
@@ -16,7 +16,10 @@ module.exports.register = function ({ config }) {
               logger.warn({ file: page.src, source: page.src.origin }, 'detected unlisted page')
               return collector.concat(page)
             }, [])
-          if (unlistedPages.length && addToNavigation) {
+          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) {
             nav.push({
               content: unlistedPagesHeading,
               items: unlistedPages.map((page) => {
@@ -36,4 +39,31 @@ function getNavEntriesByUrl (items = [], accum = {}) {
     getNavEntriesByUrl(item.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' });
+  });
 }

package/macros/rp-connect-components.js

@@ -0,0 +1,248 @@
+'use strict';
+
+module.exports.register = function (registry, context) {
+  let tabsCounter = 1; // Counter for generating unique IDs
+
+  // Add the category tabs for components
+  registry.blockMacro(function () {
+    const self = this;
+    self.named('components_by_category');
+    self.positionalAttributes(['type']);
+    self.process((parent, target, attrs) => {
+      const type = attrs.type;
+      const categoriesData = context.config?.attributes?.connectCategoriesData || {}
+      const categories = categoriesData[type] || {};
+      const currentTabsId = `tabs-${tabsCounter++}`; // Unique ID for this set of tabs
+
+      let tabsHtml = `
+<div id="${currentTabsId}" class="openblock tabs is-sync is-loaded" data-sync-group-id="${type}">
+  <div class="content">
+    <div class="ulist tablist">
+      <ul role="tablist">`;
+
+      categories.forEach((category, index) => {
+        tabsHtml += `
+        <li id="${currentTabsId}-${category.name}" class="tab" tabindex="${index === 0 ? '0' : '-1'}" role="tab" data-sync-id="${category.name}" aria-controls="${currentTabsId}-${category.name}--panel" aria-selected="${index === 0}">
+          <p>${category.name}</p>
+        </li>`;
+      });
+
+      tabsHtml += `
+      </ul>
+    </div>`;
+
+      categories.forEach((category, index) => {
+        tabsHtml += `
+    <div id="${currentTabsId}-${category.name}--panel" class="tabpanel${index === 0 ? '' : ' is-hidden'}" aria-labelledby="${currentTabsId}-${category.name}"${index === 0 ? '' : ' hidden'} role="tabpanel">
+      <div class="listingblock">
+        <div class="content">
+          <p>${category.description}</p>
+          <div class="two-column-grid">`;
+        category.items.forEach(item => {
+          tabsHtml += `
+          <a href="${item.url}" class="component-card"><strong>${item.name}</strong></a>`;
+        });
+        tabsHtml += `
+          </div>
+        </div>
+      </div>
+    </div>`;
+      });
+
+      tabsHtml += `
+  </div>
+</div>`;
+
+      return self.createBlock(parent, 'pass', tabsHtml);
+    });
+  });
+
+  // Add the searchable table of all components (component catalog)
+  registry.blockMacro(function () {
+    const self = this;
+    self.named('component_table');
+    self.process((parent, target, attrs) => {
+      const flatComponentsData = context.config?.attributes?.flatComponentsData || []
+
+      // Sort flatComponentsData alphabetically by name
+      flatComponentsData.sort((a, b) => a.name.localeCompare(b.name));
+
+      let tableHtml = `
+  <div class="table-filters">
+  <input class="table-search" type="text" id="componentTableSearch" onkeyup="filterComponentTable()" placeholder="Search for components...">
+  <select class="type-dropdown" id="supportFilter" onchange="filterComponentTable()">
+    <option value="">All Support</option>`;
+
+      // Extract unique support values for the filter
+      const uniqueSupportValues = [...new Set(flatComponentsData.map(item => item.support))];
+      uniqueSupportValues.forEach(support => {
+        tableHtml += `<option value="${support}">${support}</option>`;
+      });
+
+      tableHtml += `
+  </select>
+  <select class="type-dropdown" id="typeFilter" onchange="filterComponentTable()">
+    <option value="">All Types</option>`;
+
+      // Extract unique types for the filter
+      const uniqueTypes = [...new Set(flatComponentsData.flatMap(item => item.types.map(typeObj => typeObj.type)))];
+      uniqueTypes.forEach(type => {
+        tableHtml += `<option value="${type}">${type.charAt(0).toUpperCase() + type.slice(1)}</option>`;
+      });
+
+      tableHtml += `
+  </select>
+  </div>
+  <table class="tableblock frame-all grid-all stripes-even no-clip stretch component-table" id="componentTable">
+  <colgroup>
+    <col style="width: 33.3%;">
+    <col style="width: 33.3%;">
+    <col style="width: 33.3%;">
+  </colgroup>
+  <thead>
+    <tr>
+      <th class="tableblock halign-left valign-top">Connector</th>
+      <th class="tableblock halign-left valign-top">Support</th>
+      <th class="tableblock halign-left valign-top">Type</th>
+    </tr>
+  </thead>
+  <tbody>`;
+
+      flatComponentsData.forEach(item => {
+        const typeDropdown = item.types.length > 1
+          ? `<select class="type-dropdown" onchange="updateComponentUrl(this, true)">
+              ${item.types.map(typeObj => `<option value="${typeObj.url}">${typeObj.type.charAt(0).toUpperCase() + typeObj.type.slice(1)}</option>`).join('')}
+            </select>`
+          : item.types[0].type;
+
+        tableHtml += `
+    <tr>
+      <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="${item.types[0].url}">${item.name}</a></p></td>
+      <td class="tableblock halign-left valign-top"><p class="tableblock">${item.support}</p></td>
+      <td class="tableblock halign-left valign-top"><p class="tableblock">${typeDropdown}</p></td>
+    </tr>`;
+      });
+
+      tableHtml += `
+  </tbody>
+  </table>
+  <script>
+  function filterComponentTable() {
+  const nameInput = document.getElementById('componentTableSearch').value.toLowerCase();
+  const supportFilter = document.getElementById('supportFilter').value;
+  const typeFilter = document.getElementById('typeFilter').value;
+  const table = document.getElementById('componentTable');
+  const trs = table.getElementsByTagName('tr');
+
+  for (let i = 1; i < trs.length; i++) {
+    const nameTd = trs[i].getElementsByTagName('td')[0];
+    const supportTd = trs[i].getElementsByTagName('td')[1];
+    const typeTd = trs[i].getElementsByTagName('td')[2];
+    const typeDropdown = typeTd.querySelector('.type-dropdown');
+    let showRow =
+      (!nameInput || nameTd.textContent.toLowerCase().includes(nameInput)) &&
+      (!supportFilter || supportTd.textContent === supportFilter) &&
+      (!typeFilter || (typeDropdown ? Array.from(typeDropdown.options).some(option => option.text.toLowerCase() === typeFilter.toLowerCase()) : typeTd.textContent.toLowerCase().includes(typeFilter.toLowerCase())));
+
+    trs[i].style.display = showRow ? '' : 'none';
+
+    if (showRow && typeFilter && typeDropdown) {
+      const matchingOption = Array.from(typeDropdown.options).find(option => option.text.toLowerCase() === typeFilter.toLowerCase());
+      typeDropdown.value = matchingOption.value;
+      updateComponentUrl(typeDropdown, false);
+    }
+  }
+  }
+  function getQueryParams() {
+    const params = {};
+    const searchParams = new URLSearchParams(window.location.search);
+    searchParams.forEach((value, key) => {
+      params[key] = value;
+    });
+    return params;
+  }
+
+  function capitalizeFirstLetter(string) {
+    return string.charAt(0).toUpperCase() + string.slice(1);
+  }
+
+  function updateComponentUrl(select, redirect) {
+    const anchor = select.closest('tr').querySelector('a');
+    anchor.href = select.value;
+    if (redirect) {
+      window.location.href = select.value; // Redirect to the new URL
+    }
+  }
+  // Initialize Choices.js for type dropdowns
+  document.addEventListener('DOMContentLoaded', function() {
+    const params = getQueryParams();
+    if (params.search) {
+      document.getElementById('componentTableSearch').value = params.search;
+    }
+    if (params.support) {
+      document.getElementById('supportFilter').value = capitalizeFirstLetter(params.support);
+    }
+    if (params.type) {
+      document.getElementById('typeFilter').value = params.type;
+    }
+    filterComponentTable();
+    const typeDropdowns = document.querySelectorAll('.type-dropdown');
+    typeDropdowns.forEach(dropdown => {
+      new Choices(dropdown, { searchEnabled: false,  allowHTML: true});
+    });
+  });
+  </script>`;
+
+      return self.createBlock(parent, 'pass', tableHtml);
+    });
+  });
+  // Add the block macro for displaying a dropdown of other supported types
+  registry.blockMacro(function () {
+    const self = this;
+    self.named('component_type_dropdown');
+    self.process((parent, target, attrs) => {
+      const attributes = parent.getDocument().getAttributes();
+      const name = attributes['doctitle'];
+      const type = attributes['type'];
+
+      if (!name || !type) {
+        console.log('Name or type attribute is missing');
+        return self.createBlock(parent, 'pass', '');
+      }
+
+      const flatComponentsData = context.config?.attributes?.flatComponentsData || []
+      const component = flatComponentsData.find(item => item.originalName === name);
+
+      if (!component || component.types.length <= 1) {
+        return self.createBlock(parent, 'pass', '');
+      }
+
+      // Move the page's current type to the first position in the dropdown
+      const sortedTypes = [...component.types];
+      const currentTypeIndex = sortedTypes.findIndex(typeObj => typeObj.type === type);
+      if (currentTypeIndex !== -1) {
+        const [currentType] = sortedTypes.splice(currentTypeIndex, 1);
+        sortedTypes.unshift(currentType);
+      }
+
+      const typeDropdown = `
+<div class="page-type-dropdown">
+  <p>Type: </p>
+  <select class="type-dropdown" onchange="window.location.href=this.value">
+    ${sortedTypes.map(typeObj => `<option value="${typeObj.url}" data-support="${typeObj.support}">${typeObj.type.charAt(0).toUpperCase() + typeObj.type.slice(1)}</option>`).join('')}
+  </select>
+</div>
+<script>
+// Initialize Choices.js for type dropdowns
+document.addEventListener('DOMContentLoaded', function() {
+  const typeDropdowns = document.querySelectorAll('.type-dropdown');
+  typeDropdowns.forEach(dropdown => {
+    new Choices(dropdown, { searchEnabled: false, allowHTML: true, shouldSort: false });
+  });
+});
+</script>`;
+
+      return self.createBlock(parent, 'pass', typeDropdown);
+    });
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.2.12",
+  "version": "3.3.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -30,6 +30,7 @@
       "require": "./extensions/unlisted-pages.js"
     },
     "./extensions/replace-attributes-in-attachments": "./extensions/replace-attributes-in-attachments.js",
+    "./extensions/generate-rp-connect-categories": "./extensions/generate-rp-connect-categories.js",
     "./extensions/add-global-attributes": "./extensions/add-global-attributes.js",
     "./extensions/version-fetcher/set-latest-version": "./extensions/version-fetcher/set-latest-version.js",
     "./extensions/validate-attributes": "./extensions/validate-attributes.js",
@@ -40,6 +41,7 @@
     "./extensions/algolia-indexer/index": "./extensions/algolia-indexer/index.js",
     "./extensions/aggregate-terms": "./extensions/aggregate-terms.js",
     "./macros/glossary": "./macros/glossary.js",
+    "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",
     "./macros/helm-ref": "./macros/helm-ref.js"
   },