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

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.
 ====
@@ -133,13 +133,8 @@ 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.
-====
+- 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`.
 
 ==== 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'

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

@@ -115,7 +115,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.2",
   "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"
   }
 }