@redpanda-data/docs-extensions-and-macros 3.0.0 → 3.0.3

package/README.adoc

@@ -115,7 +115,7 @@ This extension replaces AsciiDoc attribute placeholders with their respective va
 
 [IMPORTANT]
 ====
-- By default, this extension processes attachments for the `ROOT` (redpanda) component only. This behavior is hardcoded and cannot be changed in the configuration.
+- This extension processes attachments only if the component version includes the attribute `replace-attributes-in-attachments: true`.
 - The `@` character is removed from attribute values to prevent potential issues with CSS or HTML syntax.
 - If the same attribute placeholder is used multiple times within a file, all instances will be replaced with the attribute's value.
 ====
@@ -132,14 +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>>.
-- Looks for glossary pages named `reference:glossary.adoc` in all versions of the Redpanda docs 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` macro to `reference:glossary.adoc`.
-
-[IMPORTANT]
-====
-By default, this extension processes glossary pages for the `ROOT` (redpanda) component only. This behavior is hardcoded and cannot be changed in the configuration.
-====
+- 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` so that terms can be linked to the glossary page.
 
 ==== Registration example
 

package/extensions/add-global-attributes.js

@@ -33,10 +33,12 @@ module.exports.register = function ({ config }) {
   .on('contentClassified', ({ siteCatalog, contentCatalog }) => {
     const components = contentCatalog.getComponents()
     try {
-      components.forEach(({asciidoc}) => {
-        asciidoc.attributes = _.merge(asciidoc.attributes, siteCatalog.attributeFile);
+      components.forEach(({versions}) => {
+        versions.forEach(({asciidoc}) => {
+          asciidoc.attributes = _.merge(asciidoc.attributes, siteCatalog.attributeFile);
+        })
       });
-      console.log(chalk.green('Merged global attributes into each component.'));
+      console.log(chalk.green('Merged global attributes into each component version.'));
     } catch (error) {
       logger.error(`Error merging attributes: ${error.message}`);
     }

package/extensions/aggregate-terms.js

@@ -32,8 +32,7 @@ module.exports.register = function ({ config }) {
     try {
       for (const { versions } of components) {
         for (const { name: component, version, asciidoc, title } of versions) {
-          // TODO: will need a better way to filter when we have more content components
-          if (component !== 'ROOT') continue;
+          if (component == 'shared') continue;
           const glossaryPage = contentCatalog.resolvePage(`${version?version +'@':''}${component}:reference:glossary.adoc`);
           if (glossaryPage) {
             asciidoc.attributes['glossary-page'] = 'reference:glossary.adoc'
@@ -42,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/replace-attributes-in-attachments.js

@@ -4,22 +4,17 @@ module.exports.register = function ({ config }) {
 
   const sanitizeAttributeValue = (value) => String(value).replace("@", "");
 
-  this.on('documentsConverted', ({playbook, contentCatalog}) => {
+  this.on('documentsConverted', ({contentCatalog}) => {
     for (const { versions } of contentCatalog.getComponents()) {
-      for (const { name: component, version } of versions) {
-        // TODO: will need a better way to filter when we have more content components
-        if (component !== 'ROOT') continue;
+      for (const { name: component, version, asciidoc } of versions) {
         const attachments = contentCatalog.findBy({ component, version, family });
         for (const attachment of attachments) {
           let contentString = String.fromCharCode(...attachment['_contents']);
-          const attributes = attachment.src.origin.descriptor.asciidoc.attributes;
-          const mergedAttributes = {
-            ...playbook.asciidoc.attributes,
-            ...attributes
-          };
-          for (const key in mergedAttributes) {
+          if (!asciidoc.attributes) continue
+          if (!asciidoc.attributes.hasOwnProperty('replace-attributes-in-attachments')) continue;
+          for (const key in asciidoc.attributes) {
             const placeholder = "{" + key + "}";
-            const sanitizedValue = sanitizeAttributeValue(mergedAttributes[key]);
+            const sanitizedValue = sanitizeAttributeValue(asciidoc.attributes[key]);
             contentString = contentString.replace(new RegExp(placeholder, 'g'), sanitizedValue);
           }
           attachment['_contents'] = Buffer.from(contentString, "utf-8");

package/extensions/version-fetcher/set-latest-version.js

@@ -18,6 +18,10 @@ module.exports.register = function ({ config }) {
     .on('playbookBuilt', async ({ playbook }) => {
       try {
         const LatestConsoleVersion = await GetLatestConsoleVersion();
+        if (!LatestConsoleVersion) {
+          logger.warn(`Failed to get latest Console version from GitHub`)
+          return
+        }
         if (!playbook.asciidoc) {
           playbook.asciidoc = {};
         }
@@ -37,7 +41,10 @@ module.exports.register = function ({ config }) {
         const components = await contentCatalog.getComponents();
         for (let i = 0; i < components.length; i++) {
           let component = components[i];
-          if (LatestRedpandaVersion.length !== 2) logger.warn('Could not find the latest Redpanda versions - using defaults');
+          if (LatestRedpandaVersion.length !== 2 || !LatestRedpandaVersion[0]) {
+            logger.warn('Failed to get the latest Redpanda versions - using defaults');
+            return
+          }
           if (component.name === 'ROOT') {
 
             if (!component.latest.asciidoc) {

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}`)
@@ -115,7 +131,7 @@ module.exports.register = function (registry, config = {}) {
         const attrs = glossaryTermRole ? { role: glossaryTermRole } : {}
         var inline;
         const termExistsInContext = context.gloss.some((candidate) => candidate.term === term);
-        if (termExistsInContext && links) {
+        if ((termExistsInContext && links) || (links && customLink)) {
           inline = customLink
             ? self.createInline(parent, 'anchor', target, { type: 'link', target: customLink, attributes: attrs })
             : self.createInline(parent, 'anchor', target, { type: 'xref', target: `${glossaryPage}#${termId(term)}`, reftext: target, attributes: attrs })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "3.0.0",
+  "version": "3.0.3",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -12,6 +12,10 @@
   "author": {
     "name": "Redpanda Docs Team"
   },
+  "scripts": {
+    "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
+    "serve": "wds --node-resolve --open preview/test.html --watch --root-dir docs"
+  },
   "contributors": [
     {
       "name": "JakeSCahill",
@@ -41,7 +45,6 @@
     "url": "git+https://github.com/redpanda-data/docs-extensions-and-macros"
   },
   "dependencies": {
-    "@antora/site-generator": "3.1.2",
     "@octokit/plugin-retry": "^4.1.3",
     "@octokit/rest": "^19.0.7",
     "algoliasearch": "^4.17.0",
@@ -52,5 +55,10 @@
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
     "node-html-parser": "5.4.2-0"
+  },
+  "devDependencies": {
+    "@antora/cli": "3.1.4",
+    "@antora/site-generator": "3.1.4",
+    "@web/dev-server": "^0.2.5"
   }
 }