@redpanda-data/docs-extensions-and-macros 3.0.2 → 3.0.4

package/README.adoc

@@ -132,9 +132,9 @@ antora:
 
 This extension aggregates all term pages from the {url-playbook}[`shared` component] and does the following:
 
-- Makes all `term-name` and `hover-text` attributes available to the <<glossterm-macro,`glossterm` macro>>.
+- Makes all `term-name`, `hover-text`, and `link` attributes available to the <<glossterm-macro,`glossterm` macro>>.
 - Looks for glossary pages named `reference:glossary.adoc` in all versions of all components and appends the contents of each term file to the glossary in alphabetical order.
-- If a glossary page is found, sets the `glossary-page` attribute of the <<glossterm, `glossterm` macro>> to `reference:glossary.adoc`.
+- If a glossary page is found, sets the `glossary-page` attribute of the <<glossterm, `glossterm` macro>> to `reference:glossary.adoc` so that terms can be linked to the glossary page.
 
 ==== Registration example
 

package/extensions/aggregate-terms.js

@@ -41,19 +41,37 @@ module.exports.register = function ({ config }) {
             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];
-              const termContent = siteCatalog.terms[termName];
+              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');
 
-            console.log(chalk.green(`Transposed terms into glossary for ${component}.`));
+            console.log(chalk.green(`Merged terms into glossary for ${component} component${version? version: ''}.`));
           } else {
             logger.warn(`Skipping ${title} ${version} - No glossary page (reference:glossary.adoc) found`)
           }
         }
       }
     } catch (error) {
-      logger.error(`Error transposing terms: ${error.message}`);
+      logger.error(`Error merging terms: ${error.message}`);
     }
   });
 }

package/extensions/algolia-indexer/generate-index.js

@@ -22,7 +22,6 @@ const chalk       = require('chalk')
  * @returns {SearchIndexData} A data object that contains the Algolia index
  */
 function generateIndex (playbook, contentCatalog, { indexLatestOnly = false, excludes = [], logger } = {}) {
-  if (!process.env.ALGOLIA_ADMIN_API_KEY || !process.env.ALGOLIA_APP_ID || !process.env.ALGOLIA_INDEX_NAME) return
   if (!logger) logger = process.env.NODE_ENV === 'test' ? { info: () => undefined } : console
 
   const algolia = {}

package/macros/glossary.js

@@ -23,6 +23,8 @@ module.exports.register = function (registry, config = {}) {
       // Extract the term definitions from the files
       const ATTRIBUTE_REGEX = /^:([a-zA-Z0-9_-]+):[ \t]*(.*)$/gm
 
+      const termMap = new Map();
+
       const terms = termFiles.map(file => {
         const content = file.contents.toString()
         const attributes = {}
@@ -34,15 +36,27 @@ module.exports.register = function (registry, config = {}) {
         }
 
         if (!attributes['term-name'] || !attributes['hover-text']) {
-          console.warn(`Skipping file ${file.path} due to missing 'term-name' and/or 'hover-text'.`)
+          console.warn(`Skipping term ${file.path} due to missing 'term-name' and/or 'hover-text attributes'.`)
           return null
         }
 
-        return {
+        if (termMap.has(attributes['term-name'])) {
+          throw new Error(`Error: Duplicate term-name '${attributes['term-name']}' found in ${file.src.fileUri || file.src.editUrl}.`);
+        }
+
+        termMap.set(attributes['term-name'], true);
+
+        const termObject = {
           term: attributes['term-name'],
           def: attributes['hover-text'],
           content
         }
+
+        if (attributes['link'] && attributes['link'].trim() !== '') {
+          termObject.link = attributes['link']
+        }
+
+        return termObject
       }).filter(Boolean)
 
       // Store the terms in the cache
@@ -81,9 +95,11 @@ module.exports.register = function (registry, config = {}) {
         const term = attributes.term || target
         const document = parent.document
         const context = vfs.getContext()
-        const localTerms = document.getAttribute("local-terms") || [];
-        const localTermData = (localTerms || []).find((t) => t.term === term) || {};
-        const customLink = localTermData.link;
+        const customLinkCandidate = context.gloss.find(candidate => 'link' in candidate && candidate.term === term);
+        let customLink;
+        if (customLinkCandidate) {
+          customLink = customLinkCandidate.link;
+        }
         var tooltip = document.getAttribute('glossary-tooltip')
         if (tooltip === 'true') tooltip = 'data-glossary-tooltip'
         if (tooltip && tooltip !== 'title' && !tooltip.startsWith('data-')) {
@@ -96,7 +112,7 @@ module.exports.register = function (registry, config = {}) {
         if (index >= 0) {
           definition = context.gloss[index].def
         } else {
-          definition = localTermData.definition || attributes.definition;
+          definition = attributes.definition;
         }
         if (definition) {
           logTerms && console.log(`${term}::  ${definition}`)

package/package.json

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