@redpanda-data/docs-extensions-and-macros 5.22.2 → 5.22.4

package/macros/enterprise.js

@@ -60,9 +60,9 @@
  */
 
 const yaml = require('js-yaml')
-const chalk = require('chalk')
 const semver = require('semver')
 const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
+const logger = require('@antora/logger')('enterprise-macro')
 
 const $enterpriseRegistry = Symbol('$enterpriseRegistry')
 const $enterpriseRegistryUnreadable = Symbol('$enterpriseRegistryUnreadable')
@@ -76,7 +76,7 @@ function warnOnce (contentCatalog, key, message) {
   const seen = contentCatalog[$warned] || (contentCatalog[$warned] = new Set())
   if (seen.has(key)) return false
   seen.add(key)
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
   return true
 }
 
@@ -143,7 +143,7 @@ function entryStatus (entry, report) {
       // One registry typo needs one fix, so report it once per build rather
       // than once per mention of the feature.
       if (report.contentCatalog) warnOnce(report.contentCatalog, `status:${entry.name}`, message)
-      else console.warn(chalk.yellow(message))
+      else logger.warn(message)
     }
     return STATUS_UNRELEASED
   }
@@ -167,9 +167,9 @@ function isPrereleasePage (config, document) {
     // Anything else is a typo. Falling through to the catalog is safer than
     // guessing, and silently treating it as "released" produced a warning that
     // told the writer their prerelease page belonged to a released version.
-    console.warn(chalk.yellow(
+    logger.warn(
       `enterprise macro: page-component-version-is-prerelease is '${attribute}', which is neither true nor false, so it is ignored and the component version's own prerelease flag is used instead.`
-    ))
+    )
   }
   const contentCatalog = config && config.contentCatalog
   const src = config && config.file && config.file.src
@@ -215,7 +215,7 @@ function reportUnreleasedFeature ({ feature, mode, filePath }) {
     'This page belongs to a released version, so the mention renders as plain text with no enterprise styling, tooltip, or link. ' +
     'Move the mention to the prerelease (beta) branch, or change the status once the feature ships.'
   if (mode === 'error') throw new Error(message)
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
 }
 
 /**
@@ -268,7 +268,7 @@ function isFeatureShippedOnPage (entry, config, report) {
         `enterprise:${entry.name}[]${where}: registry has since: '${since}', which is not a parsable version, so the since-gating check is skipped and the feature renders as already shipped. ` +
         'Fix the since value in enterprise-features.yml (e.g. "26.3"), or remove the key if the feature has always been available.'
       if (report.contentCatalog) warnOnce(report.contentCatalog, `since:${entry.name}`, message)
-      else console.warn(chalk.yellow(message))
+      else logger.warn(message)
     }
     return true
   }
@@ -290,7 +290,7 @@ function reportFeatureNotYetShipped ({ feature, since, pageVersion, mode, filePa
     'The mention renders as plain text with no enterprise styling, tooltip, or link. ' +
     'Move the mention to a page whose version is at or after the since version, or remove since if the feature covers this version too.'
   if (mode === 'error') throw new Error(message)
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
 }
 
 /**
@@ -418,7 +418,7 @@ function warnNoRegistry (contentCatalog) {
   if (contentCatalog) return warnOnce(contentCatalog, 'noregistry', message)
   if (warnedNoRegistry) return
   warnedNoRegistry = true
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
 }
 
 /**
@@ -434,7 +434,7 @@ function reportUnknownFeature ({ feature, mode, registry, filePath }) {
   const where = filePath ? ` in ${filePath}` : ''
   const message = `enterprise:${feature}[] does not match any feature in the enterprise features registry${where}.${hint} Add the feature to ${REGISTRY_FILENAME} in the shared component first.`
   if (mode === 'error') throw new Error(message)
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
 }
 
 /**
@@ -468,7 +468,7 @@ function resolveTooltipAttribute (raw) {
   if (raw === undefined || raw === 'title') return 'title'
   if (raw === 'true') return 'data-enterprise-tooltip'
   if (raw.startsWith('data-')) return raw
-  console.warn(`enterprise-tooltip attribute '${raw}' must be 'title', 'true', 'false', or start with 'data-'. Falling back to 'title'.`)
+  logger.warn(`enterprise-tooltip attribute '${raw}' must be 'title', 'true', 'false', or start with 'data-'. Falling back to 'title'.`)
   return 'title'
 }
 
@@ -690,7 +690,7 @@ function register (registry, config = {}) {
     registry.inlineMacro(enterpriseInlineMacro(config))
     if (typeof registry.blockMacro === 'function') registry.blockMacro(enterpriseFeaturesBlockMacro(config))
   } else {
-    console.warn("no 'inlineMacro' method on alleged registry")
+    logger.warn("no 'inlineMacro' method on alleged registry")
   }
   return registry
 }

package/macros/glossary.js

@@ -2,7 +2,7 @@
 
 const $glossaryContexts = Symbol('$glossaryContexts')
 const { posix: path } = require('path')
-const chalk = require('chalk')
+const logger = require('@antora/logger')('glossary-macro')
 
 // Backtick-monospace in hover-text. The unconstrained (double-backtick) form is
 // matched first, otherwise it leaves a stray delimiter on each side.
@@ -96,7 +96,7 @@ module.exports.register = function (registry, config = {}) {
         }
 
         if (!attributes['term-name'] || !attributes['hover-text']) {
-          console.warn(`Skipping term ${file.path} due to missing 'term-name' and/or 'hover-text attributes'.`)
+          logger.warn(`Skipping term ${file.path} due to missing 'term-name' and/or 'hover-text attributes'.`)
           return null
         }
 
@@ -169,7 +169,7 @@ module.exports.register = function (registry, config = {}) {
         var tooltip = document.getAttribute('glossary-tooltip')
         if (tooltip === 'true') tooltip = 'data-glossary-tooltip'
         if (tooltip && tooltip !== 'title' && !tooltipRendersHtml(tooltip)) {
-          console.log(`glossary-tooltip attribute '${tooltip}' must be 'true', 'title', or start with 'data-`)
+          logger.warn(`glossary-tooltip attribute '${tooltip}' must be 'true', 'title', or start with 'data-`)
           tooltip = undefined
         }
         const logTerms = document.hasAttribute('glossary-log-terms')
@@ -188,7 +188,7 @@ module.exports.register = function (registry, config = {}) {
           definitionIsHtml = !!definition;
         }
         if (definition) {
-          logTerms && console.log(`${term}:: ${definition}`)
+          logTerms && logger.info(`${term}:: ${definition}`)
         } else if (tooltip) {
           definition = `${term} not yet defined`
         }
@@ -232,7 +232,7 @@ module.exports.register = function (registry, config = {}) {
     if (typeof registry.inlineMacro === 'function') {
       registry.inlineMacro(glossaryInlineMacro())
     } else {
-      console.warn('no \'inlineMacro\' method on alleged registry')
+      logger.warn('no \'inlineMacro\' method on alleged registry')
     }
   }
 

package/macros/prop.js

@@ -90,8 +90,8 @@
  *     - '@redpanda-data/docs-extensions-and-macros/macros/prop'
  */
 
-const chalk = require('chalk')
 const semver = require('semver')
+const logger = require('@antora/logger')('prop-macro')
 
 const $propertyRegistry = Symbol('$propertyRegistry')
 // Release series a component version has no property data for, recorded at
@@ -236,7 +236,7 @@ function buildPageIndex (contentCatalog, component, properties, version) {
     return head.startsWith('<') && !head.startsWith('<<') && /^<[a-zA-Z!/]/.test(head)
   }
   if (pages.some(looksConverted)) {
-    console.warn(chalk.yellow(`prop macro: building the property page index for ${component}@${version || 'any'} after conversion started; some pages are already HTML and their properties may not be indexed. Register '@redpanda-data/docs-extensions-and-macros/extensions/property-page-index' under antora.extensions to build the index up front.`))
+    logger.warn(`prop macro: building the property page index for ${component}@${version || 'any'} after conversion started; some pages are already HTML and their properties may not be indexed. Register '@redpanda-data/docs-extensions-and-macros/extensions/property-page-index' under antora.extensions to build the index up front.`)
   }
   // A page can declare that it is the reference for a named collection of
   // properties:
@@ -404,7 +404,7 @@ function warnOnce (contentCatalog, key, message) {
   const seen = contentCatalog[$warned] || (contentCatalog[$warned] = new Set())
   if (seen.has(key)) return false
   seen.add(key)
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
   return true
 }
 
@@ -774,7 +774,7 @@ function reportUnknownProperty ({ name, mode, registry, filePath }) {
   const message = `prop:${name}[]${where}: '${name}' is not in the property data this page validates against (${describeDataset(registry)}). ` +
     `Either the name is misspelled or the property does not exist in that release.${hint}`
   if (mode === 'error') throw new Error(message)
-  console.warn(chalk.yellow(message))
+  logger.warn(message)
 }
 
 /**
@@ -799,11 +799,11 @@ function reportUnavailableProperty ({ name, component, registry, mode, filePath
   if (mode === 'off') return
   const where = filePath ? ` in ${filePath}` : ''
   const which = component || 'this'
-  console.warn(chalk.yellow(
+  logger.warn(
     `prop:${name}[]${where}: '${name}' is not available in the ${which} component, so it renders as plain code -- no link, and no tooltip. ` +
     `${describeDataset(registry)} marks it cloud_supported: false, meaning Redpanda has the property but this audience cannot set it. ` +
     'If that is wrong, fix cloud_supported in the property extractor; if it is right, reword the sentence and drop the macro.'
-  ))
+  )
 }
 
 /**
@@ -814,11 +814,11 @@ function reportUnavailableProperty ({ name, component, registry, mode, filePath
 function reportUnpublishedProperty ({ name, registry, mode, filePath }) {
   if (mode === 'off') return
   const where = filePath ? ` in ${filePath}` : ''
-  console.warn(chalk.yellow(
+  logger.warn(
     `prop:${name}[link=true]${where}: '${name}' is in ${describeDataset(registry)} but no reference page in this component renders a heading for it, so it keeps its tooltip and renders without a link. ` +
     'Every property reference page filters out the deprecated and exclude-from-docs include tags, and some include only selected category tags -- check which tags enclose this property in the generated partial. ' +
     'If it is meant to stay unpublished, drop link=true.'
-  ))
+  )
 }
 
 /**
@@ -1000,7 +1000,7 @@ function register (registry, config = {}) {
   } else if (typeof registry.inlineMacro === 'function') {
     registry.inlineMacro(propInlineMacro(config))
   } else {
-    console.warn("no 'inlineMacro' method on alleged registry")
+    logger.warn("no 'inlineMacro' method on alleged registry")
   }
   return registry
 }

package/macros/rp-connect-components.js

@@ -1,5 +1,6 @@
 'use strict';
 const { posix: path } = require('path')
+const logger = require('@antora/logger')('rp-connect-components-macro')
 
 /**
  * Registers macros for use in Redpanda Connect contexts in the Redpanda documentation.
@@ -602,7 +603,7 @@ module.exports.register = function (registry, context) {
       const showAllInfo = attributes?.all
 
       const csvData = context.config?.attributes?.csvData || null;
-      if (!csvData) return console.error(`CSV data is not available for ${parent.getDocument().getAttributes()['page-relative-src-path']}. Make sure your playbook includes the generate-rp-connect-info extension.`)
+      if (!csvData) return logger.error(`CSV data is not available for ${parent.getDocument().getAttributes()['page-relative-src-path']}. Make sure your playbook includes the generate-rp-connect-info extension.`)
 
       // Get the enriched commercial names map (includes CSV + AsciiDoc names)
       const commercialNamesMap = context.config?.attributes?.commercialNamesMap || {};
@@ -1022,11 +1023,11 @@ module.exports.register = function (registry, context) {
         return self.createBlock(parent, 'pass', '');
       }
       const csvData = context.config?.attributes?.csvData || null;
-      if (!csvData) return console.error(`CSV data is not available for ${attributes['page-relative-src-path']}. Make sure your playbook includes the generate-rp-connect-info extension.`);
+      if (!csvData) return logger.error(`CSV data is not available for ${attributes['page-relative-src-path']}. Make sure your playbook includes the generate-rp-connect-info extension.`);
       // Filter for the specific connector by name
       const componentRows = csvData.data.filter(row => row.connector.trim().toLowerCase() === name.trim().toLowerCase());
       if (componentRows.length === 0) {
-        console.warn(`No CSV data found for connector: ${name}. The connector may have been removed or renamed.`);
+        logger.warn(`No CSV data found for connector: ${name}. The connector may have been removed or renamed.`);
         // Build link to release notes using content catalog for proper URL resolution
         const isCloud = attributes['env-cloud'] !== undefined;
         let whatsNewUrl = isCloud
@@ -1092,7 +1093,7 @@ module.exports.register = function (registry, context) {
     self.process((parent, target, attrs) => {
       const type = attrs.type;
       const categoriesData = context.config?.attributes?.connectCategoriesData || null
-      if (!categoriesData) return console.error (`Category data is not available for ${parent.getDocument().getAttributes()['page-relative-src-path']}. Make sure your playbook includes the generate-rp-connect-categories extension.`)
+      if (!categoriesData) return logger.error(`Category data is not available for ${parent.getDocument().getAttributes()['page-relative-src-path']}. Make sure your playbook includes the generate-rp-connect-categories extension.`)
       const categories = categoriesData[type] || null;
       const currentTabsId = `tabs-${tabsCounter++}`; // Unique ID for this set of tabs
       if (!categories) return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.22.2",
+  "version": "5.22.4",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -159,6 +159,7 @@
     "jest-junit": "^16.0.0"
   },
   "peerDependencies": {
-    "@antora/asciidoc-loader": "^3.1.0"
+    "@antora/asciidoc-loader": "^3.1.0",
+    "@antora/logger": "^3.1.0"
   }
 }

package/tools/rpk-docs/rpk-docs-handler.js

@@ -1192,7 +1192,12 @@ function updateWhatsNewFile(diffData, whatsNewPath, version, options = {}) {
     const nextHeading = rest.search(/\n== /)
     const insertAt = nextHeading === -1 ? existingContent.length : sectionStart + nextHeading
     const before = existingContent.slice(0, insertAt).replace(/\s*$/, '\n\n')
-    const after = existingContent.slice(insertAt).replace(/^\n*/, '\n')
+    // A single newline here leaves the appended block's end marker comment
+    // directly above the next `== ` heading with no blank line between them.
+    // AsciiDoc comments don't terminate the preceding list block, so the
+    // heading is swallowed as literal list-item text instead of rendering
+    // as a heading. Needs the same blank-line separator as `before`.
+    const after = existingContent.slice(insertAt).replace(/^\n*/, '\n\n')
     fs.writeFileSync(whatsNewPath, `${before}${block}${after}`, 'utf8')
     console.log(`Appended ${version} block to the "${sectionHeading}" section in: ${whatsNewPath}`)
     return