@redpanda-data/docs-extensions-and-macros 3.0.16 → 3.0.17

package/extensions/aggregate-terms.js

@@ -6,72 +6,91 @@
 
 module.exports.register = function ({ config }) {
   const logger = this.getLogger('term-aggregation-extension');
-  const chalk = require('chalk')
+  const chalk = require('chalk');
+
+  function processTermContent(termContent) {
+    const hoverTextMatch = termContent.match(/:hover-text: (.*)/);
+    const hoverText = hoverTextMatch ? hoverTextMatch[1] : '';
+    if (hoverText && !termContent.includes('{hover-text}')) {
+      const firstNewlineIndex = termContent.indexOf('\n\n');
+      termContent = firstNewlineIndex !== -1
+        ? termContent.slice(0, firstNewlineIndex + 1) + hoverText + '\n' + termContent.slice(firstNewlineIndex + 1)
+        : termContent += '\n' + hoverText;
+    }
+
+    const linkMatch = termContent.match(/:link: (.*)/);
+    const link = linkMatch ? linkMatch[1] : '';
+    if (link) {
+      termContent += `\n\nFor more details, see ${link}`;
+    }
+
+    return termContent;
+  }
 
   this.on('contentAggregated', ({ siteCatalog, contentAggregate }) => {
     try {
+      siteCatalog.termsByCategory = {};
+
       for (const component of contentAggregate) {
         if (component.name === 'shared') {
           const termFiles = component.files.filter(file => file.path.includes('modules/terms/partials/'));
-          siteCatalog.terms = {}
+
           termFiles.forEach(file => {
             const termContent = file.contents.toString('utf8');
-            siteCatalog.terms[file.basename] = termContent;
+            const categoryMatch = /:category: (.*)/.exec(termContent);
+            var category = categoryMatch ? categoryMatch[1] : 'Miscellaneous'; // Default category
+
+            category = category.charAt(0).toUpperCase() + category.slice(1);
+
+            if (!siteCatalog.termsByCategory[category]) {
+              siteCatalog.termsByCategory[category] = [];
+            }
+
+            siteCatalog.termsByCategory[category].push({ name: file.basename, content: termContent });
           });
-          console.log(chalk.green('Loaded terms from shared component.'));
-          break
+
+          console.log(chalk.green('Categorized terms from shared component.'));
+          break;
         }
       }
     } catch (error) {
-      logger.error(`Error loading terms: ${error.message}`);
+      logger.error(`Error categorizing terms: ${error.message}`);
     }
   })
 
   .on('contentClassified', ({ siteCatalog, contentCatalog }) => {
-    const components = contentCatalog.getComponents()
+    const components = contentCatalog.getComponents();
     try {
-      for (const { versions } of components) {
-        for (const { name: component, version, asciidoc, title } of versions) {
-          if (component == 'shared') continue;
-          const glossaryPage = contentCatalog.resolvePage(`${version?version +'@':''}${component}:reference:glossary.adoc`);
+      components.forEach(({ versions }) => {
+        versions.forEach(({ name: component, version, asciidoc, title }) => {
+          if (component == 'shared') return;
+
+          const glossaryPage = contentCatalog.resolvePage(`${version ? version + '@' : ''}${component}:reference:glossary.adoc`);
+
           if (glossaryPage) {
-            asciidoc.attributes['glossary-page'] = 'reference:glossary.adoc'
-            const glossaryContent = glossaryPage.contents.toString('utf8');
-            let newContent = glossaryContent;
-            const sortedTerms = Object.keys(siteCatalog.terms).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
-            for (i = 0; i < sortedTerms.length; i++) {
-              const termName = sortedTerms[i];
-              let termContent = siteCatalog.terms[termName];
-              const hoverTextMatch = termContent.match(/:hover-text: (.*)/);
-              const hoverText = hoverTextMatch ? hoverTextMatch[1] : '';
-              const linkMatch = termContent.match(/:link: (.*)/);
-              const link = linkMatch ? linkMatch[1] : '';
-              // If the hover-text attribute is found and the content does not already contain {hover-text}, append it as a new line after the first newline
-              if (hoverText && !termContent.includes('{hover-text}')) {
-                const firstNewlineIndex = termContent.indexOf('\n\n');
-                if (firstNewlineIndex !== -1) {
-                  termContent = termContent.slice(0, firstNewlineIndex + 1) + hoverText + '\n' + termContent.slice(firstNewlineIndex + 1);
-                } else {
-                  // If there's no newline, just append at the end
-                  termContent += '\n' + hoverText;
-                }
-              }
-              // If the link attribute is found, append it at the end of the term content
-              if (link) {
-                termContent += `\n\nFor more details, see ${link}`;
-              }
-              newContent += '\n\n' + termContent;
-            }
-            glossaryPage.contents = Buffer.from(newContent, 'utf8');
+            asciidoc.attributes['glossary-page'] = 'reference:glossary.adoc';
+            let glossaryContent = glossaryPage.contents.toString('utf8');
 
-            console.log(chalk.green(`Merged terms into glossary for ${component} component${version? version: ''}.`));
+            Object.keys(siteCatalog.termsByCategory).sort().forEach(category => {
+              let categoryContent = `\n\n== ${category}\n`;
+
+              siteCatalog.termsByCategory[category].sort((a, b) => a.name.localeCompare(b.name)).forEach(term => {
+                let processedContent = processTermContent(term.content);
+                categoryContent += `\n\n${processedContent}`;
+              });
+
+              glossaryContent += categoryContent;
+            });
+
+            glossaryPage.contents = Buffer.from(glossaryContent, 'utf8');
+            console.log(chalk.green(`Merged terms into glossary for ${component} component${version ? ' version ' + version : ''}.`));
           } else {
-            logger.info(`Skipping ${title} ${version} - No glossary page (reference:glossary.adoc) found`)
+            logger.info(`Skipping ${title} ${version ? ' version ' + version : ''} - No glossary page (reference:glossary.adoc) found`);
           }
-        }
-      }
+        });
+      });
     } catch (error) {
       logger.error(`Error merging terms: ${error.message}`);
     }
   });
-}
+};

package/macros/glossary.js

@@ -49,6 +49,7 @@ module.exports.register = function (registry, config = {}) {
         const termObject = {
           term: attributes['term-name'],
           def: attributes['hover-text'],
+          category: attributes['category'] || '',
           content
         }
 
@@ -115,7 +116,7 @@ module.exports.register = function (registry, config = {}) {
           definition = attributes.definition;
         }
         if (definition) {
-          logTerms && console.log(`${term}::  ${definition}`)
+          logTerms && console.log(`${term}:: ${definition}`)
         } else if (tooltip) {
           definition = `${term} not yet defined`
         }

package/package.json

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