@redpanda-data/docs-extensions-and-macros 5.22.1 → 5.22.3

package/bin/doc-tools.js

@@ -901,7 +901,7 @@ automation
  * @description
  * One-time migration that rewires published connector reference pages onto the
  * regenerated description partial: the header `:description:` becomes
- * `include::...[tag=attrs]` and the frozen intro prose becomes
+ * `include::...[tag=meta]` and the frozen intro prose becomes
  * `include::...[tag=body]`. Afterwards `generate rpcn-connector-docs` keeps
  * both fresh on every run.
  *

package/extensions/README.adoc

@@ -64,7 +64,6 @@ IMPORTANT: Extensions must be registered under the `antora.extensions` key in yo
 
 === Navigation
 * **unlisted-pages** - Manage pages that appear in navigation but aren't listed
-* **produce-redirects** - Generate redirect configurations
 * **unpublish-pages** - Mark pages as unpublished
 
 === Integrations
@@ -125,13 +124,16 @@ antora:
       algolia_index_name: YOUR_INDEX
 ----
 
-=== Generate redirects
+=== Redirects
+
+No extension required: core Antora (>= 3.1.8) generates redirects for https://docs.antora.org/antora/latest/page/page-aliases/[page aliases] automatically on every build. Define aliases in your `antora.yml`:
 
 [,yaml]
 ----
-antora:
-  extensions:
-    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'
+name: redpanda
+asciidoc:
+  attributes:
+    page-aliases: old-page.adoc,another-old-page.adoc
 ----
 
 == Support

package/extensions/REFERENCE.adoc

@@ -706,23 +706,7 @@ In this example, the `attributespath` option points to a local YAML file (`./loc
 
 == Produce redirects (customization of core Antora)
 
-This extension replaces the default https://gitlab.com/antora/antora/-/tree/v3.1.x/packages/redirect-producer[`produceRedirects()` function] in Antora to handle redirect loops caused by https://docs.antora.org/antora/latest/page/page-aliases/[page aliases]. Normally, page aliases in Antora are used to resolve outdated links without causing issues. However, with https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/#html-extension-style-key[`indexify`], the same URL may inadvertently be used for both the source and target of a redirect, leading to loops. This problem is https://antora.zulipchat.com/#narrow/stream/282400-users/topic/Redirect.20Loop.20Issue.20with.20Page.20Renaming.20and.20Indexify/near/433691700[recognized as a bug] in core Antora. For example, creating a page alias for `modules/manage/security/authorization.adoc` to point to `modules/manage/security/authorization/index.adoc' can lead to a redirect loop where `manage/security/authorization/` points to `manage/security/authorization/`. Furthermore, omitting the alias would lead to `xref not found` errors because Antora relies on the alias to resolve the old xrefs. This extension is necessary until such behaviors are natively supported or fixed in Antora core.
-
-=== Environment variables
-
-This extension does not require any environment variables.
-
-=== Configuration options
-
-There are no configurable options for this extension.
-
-=== Registration
-
-```yaml
-antora:
-  extensions:
-  - '@redpanda-data/docs-extensions-and-macros/extensions/modify-redirects'
-```
+Antora's built-in `@antora/redirect-producer` already produces redirect rules for https://docs.antora.org/antora/latest/page/page-aliases/[page aliases], including the redirect-loop case caused by https://docs.antora.org/antora/latest/playbook/urls-html-extension-style/#html-extension-style-key[`indexify`] that once required a workaround. Antora runs the real module automatically on every build with no extension required. This project previously shipped a hand-copied override of that module to work around the loop, but the override had drifted from the upstream fix and reintroduced a worse bug (a self-referential alias could overwrite the real page it pointed at). The override has been removed; core Antora handles redirects natively.
 
 == Replace attributes in attachments
 

package/extensions/USER_GUIDE.adoc

@@ -85,7 +85,6 @@ antora:
   extensions:
     - '@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/set-latest-version'
     - '@redpanda-data/docs-extensions-and-macros/extensions/generate-index-data.js'
-    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'
 ----
 
 Extensions run in the order they're listed.
@@ -122,16 +121,7 @@ antora:
 
 === Redirect management
 
-Generate redirects from old URLs to new ones:
-
-[,yaml]
-----
-antora:
-  extensions:
-    - '@redpanda-data/docs-extensions-and-macros/extensions/produce-redirects.js'
-----
-
-Define redirects in your `antora.yml`:
+No extension required: core Antora (>= 3.1.8) generates redirects for old URLs automatically. Define redirects in your `antora.yml`:
 
 [,yaml]
 ----

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,62 @@
 
 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.
+const MONOSPACE_RX = /``([^`]+)``|`([^`]+)`/g
+
+// Escape for interpolation into a double-quoted HTML attribute. Same four
+// replacements, in the same order, as badge.js and enterprise.js; `&` has to go
+// first or it re-escapes the entities the later passes introduce.
+function escapeAttr (value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+// Only a data-* tooltip is read by a JS tooltip library that renders it as HTML;
+// the native title attribute is always plain text. Shared with the
+// glossary-tooltip validation below so the two cannot drift apart.
+function tooltipRendersHtml (tooltipAttr) {
+  return typeof tooltipAttr === 'string' && tooltipAttr.startsWith('data-')
+}
+
+// hover-text is raw, unconverted source text, so it has to be escaped before it
+// lands in an HTML attribute. How many passes depends on the consumer:
+//
+//   title   The browser decodes the attribute once and shows the result as
+//           text, so one pass is exactly right.
+//   data-*  docs-ui initializes tippy on these with allowHTML: true
+//           (docs-ui/src/js/12-activate-tooltips.js), which means the value is
+//           decoded once by the HTML parser and then parsed AGAIN as HTML by
+//           innerHTML. A single pass is spent on that first decode and escaped
+//           markup comes back to life -- `<img onerror=...>` in hover-text
+//           became a live element that fired. Escape twice so one level
+//           survives the decode, and add <code> afterwards so it is the only
+//           live markup in the value.
+//
+// Set definitionIsHtml for a definition that Asciidoctor already converted --
+// the inline glossterm:term[definition] form arrives as HTML, unlike a term
+// file's raw :hover-text: value -- so it is escaped once rather than twice and
+// its markup survives to the reader instead of being shown as literal tags.
+function formatTooltipDefinition (text, tooltipAttr, definitionIsHtml) {
+  if (!tooltipRendersHtml(tooltipAttr)) return escapeAttr(text)
+  if (definitionIsHtml) {
+    // Already HTML, so one pass is right: the attribute decode hands the markup
+    // back intact for innerHTML to render, and a quote in the text still cannot
+    // terminate the attribute early.
+    return escapeAttr(text)
+  }
+  return escapeAttr(escapeAttr(text)).replace(
+    MONOSPACE_RX,
+    (match, unconstrained, constrained) =>
+      `<code>${unconstrained !== undefined ? unconstrained : constrained}</code>`
+  )
+}
 
 module.exports.register = function (registry, config = {}) {
 
@@ -41,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
         }
 
@@ -113,22 +168,27 @@ module.exports.register = function (registry, config = {}) {
         }
         var tooltip = document.getAttribute('glossary-tooltip')
         if (tooltip === 'true') tooltip = 'data-glossary-tooltip'
-        if (tooltip && tooltip !== 'title' && !tooltip.startsWith('data-')) {
-          console.log(`glossary-tooltip attribute '${tooltip}' must be 'true', 'title', or start with 'data-`)
+        if (tooltip && tooltip !== 'title' && !tooltipRendersHtml(tooltip)) {
+          logger.warn(`glossary-tooltip attribute '${tooltip}' must be 'true', 'title', or start with 'data-`)
           tooltip = undefined
         }
         const logTerms = document.hasAttribute('glossary-log-terms')
         var definition;
         var pageTitle;
+        // A term file's :hover-text: is raw source text, but the definition
+        // passed inline as glossterm:term[definition] has already been through
+        // Asciidoctor's inline substitutions, so the two need different escaping.
+        var definitionIsHtml = false;
         const index = context.gloss.findIndex((candidate) => candidate.term === term)
         if (index >= 0) {
           definition = context.gloss[index].def
           pageTitle = context.gloss[index].pageTitle
         } else {
           definition = attributes.definition;
+          definitionIsHtml = !!definition;
         }
         if (definition) {
-          logTerms && console.log(`${term}:: ${definition}`)
+          logTerms && logger.info(`${term}:: ${definition}`)
         } else if (tooltip) {
           definition = `${term} not yet defined`
         }
@@ -154,12 +214,13 @@ module.exports.register = function (registry, config = {}) {
           inline = self.createInline(parent, 'quoted', customText, { attributes: attrs })
         }
         if (tooltip) {
+          const formattedDefinition = formatTooltipDefinition(definition, tooltip, definitionIsHtml)
           const a = inline.convert()
           const matches = a.match(TRX)
           if (matches) {
-            return self.createInline(parent, 'quoted', `${matches[1]} ${tooltip}="${definition}"${matches[2]}`)
+            return self.createInline(parent, 'quoted', `${matches[1]} ${tooltip}="${formattedDefinition}"${matches[2]}`)
           } else {
-            return self.createInline(parent, 'quoted', `<span ${tooltip}="${definition}">${a}</span>`)
+            return self.createInline(parent, 'quoted', `<span ${tooltip}="${formattedDefinition}">${a}</span>`)
           }
         }
         return inline
@@ -171,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')
     }
   }
 
@@ -186,3 +247,5 @@ module.exports.register = function (registry, config = {}) {
   }
   return registry
 }
+
+module.exports.formatTooltipDefinition = formatTooltipDefinition

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.1",
+  "version": "5.22.3",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -77,8 +77,6 @@
     "./extensions/find-related-labs": "./extensions/find-related-labs.js",
     "./extensions/convert-llms-to-txt": "./extensions/convert-llms-to-txt.js",
     "./extensions/convert-sitemap-to-markdown": "./extensions/convert-sitemap-to-markdown.js",
-    "./extensions/modify-redirects": "./extensions/produce-redirects.js",
-    "./extensions/produce-redirects": "./extensions/produce-redirects.js",
     "./extensions/algolia-indexer/index": "./extensions/algolia-indexer/index.js",
     "./extensions/aggregate-terms": "./extensions/aggregate-terms.js",
     "./extensions/resolve-xrefs-in-attachments": "./extensions/resolve-xrefs-in-attachments.js",
@@ -161,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/redpanda-connect/generate-rpcn-connector-docs.js

@@ -43,8 +43,8 @@ const STALE_METADATA_PARTIAL =
 // deleting the file would break any published page that includes it, so blank
 // it instead and log so a human removes the include line.
 //
-// The empty attrs/body regions are load-bearing. Pages include this file with
-// `[tag=attrs]` and `[tag=body]`, and Asciidoctor logs `tag 'attrs' not found
+// The empty meta/body regions are load-bearing. Pages include this file with
+// `[tag=meta]` and `[tag=body]`, and Asciidoctor logs `tag 'meta' not found
 // in include file` for every tag a target does not define -- so a banner
 // without the regions turns one blanked partial into two build warnings on
 // every page that includes it, on every build, which is a build failure
@@ -54,7 +54,7 @@ const STALE_DESCRIPTION_PARTIAL =
   '// This content is autogenerated. Do not edit manually. ' +
   'The connector no longer has a description, so this partial is intentionally empty. ' +
   'You can remove the include directive that points at this file from the connector page.\n' +
-  '\n// tag::attrs[]\n// end::attrs[]\n' +
+  '\n// tag::meta[]\n// end::meta[]\n' +
   '\n// tag::body[]\n// end::body[]\n';
 
 // Component families with their own reference pages, keyed by the canonical
@@ -606,12 +606,12 @@ async function generateRpcnConnectorDocs(options) {
           // connectors with neither summary nor description, keep the inline
           // text rather than getting an include that cannot resolve.
           item.hasDescriptionPartial = true;
-          // The attrs region only sets :description: when the connector has a
+          // The meta region only sets :description: when the connector has a
           // summary, so a page may only replace its header attribute with the
           // include when there is one. Otherwise the page would lose its meta
           // description entirely and keep the inline attribute instead.
           if (typeof item.summary === 'string' && item.summary.trim()) {
-            item.hasDescriptionAttrs = true;
+            item.hasDescriptionMeta = true;
           }
           if (!writeFullDrafts) {
             partialsWritten++;
@@ -988,7 +988,7 @@ function backfillPageDescriptions (connectorData, { pagesRoot, dryRun = false }
       const lines = content.split('\n');
       const headerEnd = lines.findIndex((l) => l.trim() === '');
       const header = lines.slice(0, headerEnd === -1 ? lines.length : headerEnd);
-      // A page migrated to the description partial carries the attrs include
+      // A page migrated to the description partial carries the meta include
       // instead of a literal :description:. Without this arm the backfill
       // splices a competing meta block into every migrated page, so the page
       // ends up with a dead include plus a hand-inserted attribute that
@@ -997,7 +997,7 @@ function backfillPageDescriptions (connectorData, { pagesRoot, dryRun = false }
 
       // Meta descriptions are read as plain text by search results, link
       // previews, and assistants, so the markup comes out mechanically. Same
-      // flattener the description partial's attrs region uses, so a page
+      // flattener the description partial's meta region uses, so a page
       // cannot publish one meta description before migrating to the partial
       // and a different one after.
       const summary = flattenToAttributeValue(item.summary);

package/tools/redpanda-connect/helpers/descriptionInclude.js

@@ -6,7 +6,7 @@ const { descriptionIncludeLine } = require('../metadata-utils.js');
  * Handlebars helper: emit the include directive for a connector's description
  * partial, optionally for one of its tag regions.
  *
- *   {{{descriptionInclude this 'attrs'}}}
+ *   {{{descriptionInclude this 'meta'}}}
  *   {{{descriptionInclude this 'body'}}}
  *
  * Drafted pages use this instead of freezing the summary and description into
@@ -16,7 +16,7 @@ const { descriptionIncludeLine } = require('../metadata-utils.js');
  * writes the file.
  *
  * @param {object} item connector data with `type`/`typeDir` and `name`
- * @param {string} [tag] `attrs` or `body`
+ * @param {string} [tag] `meta` or `body`
  * @returns {string}
  */
 module.exports = function descriptionInclude (item, tag) {

package/tools/redpanda-connect/helpers/summaryAttribute.js

@@ -7,7 +7,7 @@ const { flattenToAttributeValue } = require('../metadata-utils.js');
  * value suitable for the `:description:` page attribute (and therefore for the
  * page's `<meta name="description">`).
  *
- * Delegates to the shared flattener so the description partial's attrs region
+ * Delegates to the shared flattener so the description partial's meta region
  * and `backfillPageDescriptions` publish the same text for the same summary.
  * Collapsing whitespace alone is not enough: summaries carry xrefs, link
  * macros and inline code, and an unflattened value ships raw

package/tools/redpanda-connect/metadata-utils.js

@@ -248,10 +248,10 @@ function descriptionWithMetadataInclude (item) {
  * auto-generated summary and description from a regenerated partial instead of
  * freezing them into the page body at first draft.
  *
- * The partial defines two tag regions, so pages address it twice: `attrs` in
+ * The partial defines two tag regions, so pages address it twice: `meta` in
  * the page header (sets `:description:`) and `body` where the prose renders.
  * @param {object} item connector data with `type`/`typeDir` and `name`
- * @param {string} [tag] tag region to include (`attrs` or `body`); omit for the whole file
+ * @param {string} [tag] tag region to include (`meta` or `body`); omit for the whole file
  * @returns {string}
  */
 function descriptionIncludeLine (item, tag) {
@@ -308,7 +308,7 @@ function lostMetadataSections (oldContent, newContent) {
  * edited.
  *
  * This is the one implementation: `summaryAttribute` (the description
- * partial's attrs region) and `backfillPageDescriptions` (the page-header
+ * partial's meta region) and `backfillPageDescriptions` (the page-header
  * self-heal) both call it, so the two paths cannot drift into publishing
  * different meta descriptions for the same summary.
  *

package/tools/redpanda-connect/migrate-descriptions-to-partials.js

@@ -11,7 +11,7 @@
  * to `modules/components/partials/descriptions/<type>/<name>.adoc` on every
  * run, with two tag regions. This script rewires existing pages to it:
  *
- *   header: include::...[tag=attrs]  inside the page's `// tag::meta[]` region
+ *   header: include::...[tag=meta]   inside the page's `// tag::meta[]` region
  *   body:   include::...[tag=body]   where the frozen prose is today
  *
  * The header rewire is mechanical and safe: it swaps one `:description:` line
@@ -36,7 +36,7 @@ const path = require('path');
 const { descriptionIncludeLine, normalizeTypeDir, flattenToAttributeValue } = require('./metadata-utils.js');
 
 // The page's meta tag region: the block single-source stubs inherit
-// :description: from, so the attrs include belongs inside it.
+// :description: from, so the meta include belongs inside it.
 const META_TAG_OPEN = /^\/\/\s*tag::meta\[\]\s*$/;
 const META_TAG_CLOSE = /^\/\/\s*end::meta\[\]\s*$/;
 
@@ -123,34 +123,34 @@ function migrateDescriptionsToPartials ({
         continue;
       }
       const partial = fs.readFileSync(partialPath, 'utf8');
-      const attrs = tagRegion(partial, 'attrs');
+      const meta = tagRegion(partial, 'meta');
       const body = tagRegion(partial, 'body');
-      if (!attrs || !body || contentLines(body).length === 0) {
+      if (!meta || !body || contentLines(body).length === 0) {
         // A blanked partial (description removed upstream) has both regions
         // but no content. Wiring a page to it would publish an empty page.
         results.skipped.push({ page: key, reason: 'description partial is empty' });
         continue;
       }
 
-      const includeAttrs = descriptionIncludeLine({ typeDir: partialTypeDir, name }, 'attrs');
+      const includeMeta = descriptionIncludeLine({ typeDir: partialTypeDir, name }, 'meta');
       const includeBody = descriptionIncludeLine({ typeDir: partialTypeDir, name }, 'body');
 
       let lines = fs.readFileSync(pagePath, 'utf8').split('\n');
       let changed = false;
 
       // --- header ---------------------------------------------------------
-      if (!lines.some((l) => l.trim() === includeAttrs)) {
+      if (!lines.some((l) => l.trim() === includeMeta)) {
         const open = lines.findIndex((l) => META_TAG_OPEN.test(l));
         const close = lines.findIndex((l, i) => i > open && META_TAG_CLOSE.test(l));
-        const attrValue = contentLines(attrs)
+        const metaValue = contentLines(meta)
           .find((l) => l.startsWith(':description:'));
         const pageAttr = lines.slice(0, introOf(lines)).find((l) => l.startsWith(':description:'));
-        if (!attrValue) {
-          // The connector has no summary, so the attrs region sets nothing.
+        if (!metaValue) {
+          // The connector has no summary, so the meta region sets nothing.
           // Replacing a hand-written :description: with it would drop the
           // page's meta description.
-          results.skipped.push({ page: key, reason: 'attrs region sets no :description:' });
-        } else if (pageAttr && flattenToAttributeValue(pageAttr) !== flattenToAttributeValue(attrValue)) {
+          results.skipped.push({ page: key, reason: 'meta region sets no :description:' });
+        } else if (pageAttr && flattenToAttributeValue(pageAttr) !== flattenToAttributeValue(metaValue)) {
           // The page's meta description is not the connector summary, so it
           // was authored by hand (often tuned for search) and swapping in the
           // include would silently discard that editorial work. 13 pages in
@@ -159,7 +159,7 @@ function migrateDescriptionsToPartials ({
           // header alone.
           results.skipped.push({ page: key, reason: 'hand-authored :description: differs from the summary (needs a human)' });
         } else if (open !== -1 && close > open) {
-          lines.splice(open + 1, close - open - 1, includeAttrs);
+          lines.splice(open + 1, close - open - 1, includeMeta);
           results.headers.push(key);
           changed = true;
         } else {
@@ -169,7 +169,7 @@ function migrateDescriptionsToPartials ({
           // :description: lines in the first place.
           const attrLine = lines.findIndex((l) => l.startsWith(':description:'));
           if (attrLine !== -1 && attrLine < introOf(lines)) {
-            lines.splice(attrLine, 1, '// tag::meta[]', includeAttrs, '// end::meta[]');
+            lines.splice(attrLine, 1, '// tag::meta[]', includeMeta, '// end::meta[]');
             results.headers.push(key);
             changed = true;
           } else {
@@ -183,7 +183,7 @@ function migrateDescriptionsToPartials ({
       // it could not see and the page ended up with two. AsciiDoc takes the
       // last assignment, so leaving the literal one there would make the
       // include a no-op and the page would keep publishing frozen text.
-      if (lines.some((l) => l.trim() === includeAttrs)) {
+      if (lines.some((l) => l.trim() === includeMeta)) {
         for (let i = introOf(lines) - 1; i >= 0; i--) {
           if (lines[i].startsWith(':description:')) {
             lines.splice(i, 1);

package/tools/redpanda-connect/templates/connector.hbs

@@ -3,9 +3,9 @@
 :type: {{type}}
 {{#if support}}:support: {{support}}{{/if}}
 :categories: [{{join categories ", "}}]
-{{#if hasDescriptionAttrs}}
+{{#if hasDescriptionMeta}}
 // tag::meta[]
-{{{descriptionInclude this "attrs"}}}
+{{{descriptionInclude this "meta"}}}
 // end::meta[]
 {{else if summary}}
 // tag::meta[]
@@ -16,7 +16,7 @@
 :description: {{{summaryAttribute description}}}
 // end::meta[]
 {{/if}}
-{{!-- The attrs include stays inside the meta tag region so single-source
+{{!-- The meta include stays inside the meta tag region so single-source
      stubs keep inheriting :description: as a header attribute, and the
      value now refreshes with the connector instead of being frozen at
      first draft. Component families with no description partial keep the

package/tools/redpanda-connect/templates/descriptions-partials.hbs

@@ -2,12 +2,12 @@
 // This content is autogenerated. Do not edit manually. The summary and description come from the connector's definition in the Connect source. To change them, update the connector upstream, or use the doc-tools CLI with the --overrides option: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1247543314/Generate+reference+docs+for+Redpanda+Connect
 //
 // Pages consume this partial in two places so both stay fresh:
-//   header: include::...[tag=attrs]  (sets :description: for search snippets and meta tags)
+//   header: include::...[tag=meta]  (sets :description: for search snippets and meta tags)
 //   body:   include::...[tag=body]   (renders the summary and description)
 
-// tag::attrs[]
+// tag::meta[]
 {{#if summary}}:description: {{{summaryAttribute summary}}}
-{{/if}}// end::attrs[]
+{{/if}}// end::meta[]
 
 // tag::body[]
 {{#if summary}}{{{summary}}}

package/extensions/produce-redirects.js

@@ -1,166 +0,0 @@
-'use strict';
-
-const { raiseListenerLimit } = require('./util/raise-listener-limit')
-
-const File = require('vinyl')
-const { posix: path } = require('path')
-
-const ENCODED_SPACE_RX = /%20/g
-
-module.exports.register = function () {
-  raiseListenerLimit(this)
-  this.once('contextStarted', () => {
-    const { publishFiles: produceRedirectsDelegate } = this.getFunctions()
-    this.replaceFunctions({
-      produceRedirects (playbook, aliases) {
-        if ('findBy' in aliases) aliases = aliases.findBy({ family: 'alias' }) // @deprecated remove in Antora 4
-        if (!(aliases = aliases.filter((it) => it.pub.url !== it.rel.pub.url)).length) return []
-        let siteUrl = playbook.site.url
-        if (siteUrl) siteUrl = stripTrailingSlash(siteUrl, '')
-        const directoryRedirects = (playbook.urls.htmlExtensionStyle || 'default') !== 'default'
-        switch (playbook.urls.redirectFacility) {
-          case 'gitlab':
-            return createNetlifyRedirects(aliases, extractUrlPath(siteUrl), !directoryRedirects, false)
-          case 'httpd':
-            return createHttpdHtaccess(aliases, extractUrlPath(siteUrl), directoryRedirects)
-          case 'netlify':
-            return createNetlifyRedirects(aliases, extractUrlPath(siteUrl), !directoryRedirects)
-          case 'nginx':
-            return createNginxRewriteConf(aliases, extractUrlPath(siteUrl))
-          case 'static':
-            return populateStaticRedirectFiles(
-              aliases.filter((it) => it.out),
-              siteUrl
-            )
-          default:
-            return unpublish(aliases)
-        }
-      }
-    })
-  })
-}
-
-function createStaticRedirectContents (file, siteUrl) {
-  const targetUrl = file.rel.pub.url
-  let linkTag
-  let to = targetUrl.charAt() === '/' ? computeRelativeUrlPath(file.pub.url, targetUrl) : undefined
-  let toText = to
-  if (to) {
-    if (siteUrl && siteUrl.charAt() !== '/') {
-      linkTag = `<link rel="canonical" href="${(toText = siteUrl + targetUrl)}">\n`
-    }
-  } else {
-    linkTag = `<link rel="canonical" href="${(toText = to = targetUrl)}">\n`
-  }
-  return `<!DOCTYPE html>
-<meta charset="utf-8">
-${linkTag || ''}<script>location="${to}"</script>
-<meta http-equiv="refresh" content="0; url=${to}">
-<meta name="robots" content="noindex">
-<title>Redirect Notice</title>
-<h1>Redirect Notice</h1>
-<p>The page you requested has been relocated to <a href="${to}">${toText}</a>.</p>`
-}
-
-function extractUrlPath (url) {
-  if (url) {
-    if (url.charAt() === '/') return url
-    const urlPath = new URL(url).pathname
-    return urlPath === '/' ? '' : urlPath
-  } else {
-    return ''
-  }
-}
-
-function createHttpdHtaccess (files, urlPath, directoryRedirects = false) {
-  const rules = files.reduce((accum, file) => {
-    delete file.out
-    let fromUrl = file.pub.url
-    fromUrl = ~fromUrl.indexOf('%20') ? `'${urlPath}${fromUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + fromUrl
-    let toUrl = file.rel.pub.url
-    toUrl = ~toUrl.indexOf('%20') ? `'${urlPath}${toUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + toUrl
-    // see https://httpd.apache.org/docs/current/en/mod/mod_alias.html#redirect
-    // NOTE: redirect rule for directory prefix does not require trailing slash
-    if (file.pub.splat) {
-      accum.push(`Redirect 302 ${fromUrl} ${stripTrailingSlash(toUrl)}`)
-    } else if (directoryRedirects) {
-      accum.push(`RedirectMatch 301 ^${regexpEscape(fromUrl)}$ ${stripTrailingSlash(toUrl)}`)
-    } else {
-      accum.push(`Redirect 301 ${fromUrl} ${toUrl}`)
-    }
-    return accum
-  }, [])
-  return [new File({ contents: Buffer.from(rules.join('\n') + '\n'), out: { path: '.htaccess' } })]
-}
-
-// NOTE: a trailing slash on the pathname will be ignored
-// see https://docs.netlify.com/routing/redirects/redirect-options/#trailing-slash
-// however, we keep it when generating the rules for clarity
-function createNetlifyRedirects (files, urlPath, addDirectoryRedirects = false, useForceFlag = true) {
-  const rules = files.reduce((accum, file) => {
-    delete file.out
-    const fromUrl = urlPath + file.pub.url
-    const toUrl = urlPath + file.rel.pub.url
-    const forceFlag = useForceFlag ? '!' : ''
-    if (file.pub.splat) {
-      accum.push(`${fromUrl}/* ${ensureTrailingSlash(toUrl)}:splat 302${forceFlag}`)
-    } else {
-      accum.push(`${fromUrl} ${toUrl} 301${forceFlag}`)
-      if (addDirectoryRedirects && fromUrl.endsWith('/index.html')) {
-        accum.push(`${fromUrl.substr(0, fromUrl.length - 10)} ${toUrl} 301${forceFlag}`)
-      }
-    }
-    return accum
-  }, [])
-  return [new File({ contents: Buffer.from(rules.join('\n') + '\n'), out: { path: '_redirects' } })]
-}
-
-function createNginxRewriteConf (files, urlPath) {
-  const rules = files.map((file) => {
-    delete file.out
-    let fromUrl = file.pub.url
-    fromUrl = ~fromUrl.indexOf('%20') ? `'${urlPath}${fromUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + fromUrl
-    let toUrl = file.rel.pub.url
-    toUrl = ~toUrl.indexOf('%20') ? `'${urlPath}${toUrl.replace(ENCODED_SPACE_RX, ' ')}'` : urlPath + toUrl
-    if (file.pub.splat) {
-      const toUrlWithTrailingSlash = ensureTrailingSlash(toUrl)
-      return `location ^~ ${fromUrl}/ { rewrite ^${regexpEscape(fromUrl)}/(.*)$ ${toUrlWithTrailingSlash}$1 redirect; }`
-    } else {
-      return `location = ${fromUrl} { return 301 ${toUrl}; }`
-    }
-  })
-  return [new File({ contents: Buffer.from(rules.join('\n').trim() + '\n'), out: { path: '.etc/nginx/rewrite.conf' } })]
-}
-
-function populateStaticRedirectFiles(files, siteUrl) {
-  for (const file of files) {
-    const content = createStaticRedirectContents(file, siteUrl) + '\n';
-    file.contents = Buffer.from(content);
-  }
-  return []
-}
-
-function unpublish (files) {
-  files.forEach((file) => delete file.out)
-  return []
-}
-
-function computeRelativeUrlPath (from, to) {
-  if (to === from) return to.charAt(to.length - 1) === '/' ? './' : path.basename(to)
-  return (path.relative(path.dirname(from + '.'), to) || '.') + (to.charAt(to.length - 1) === '/' ? '/' : '')
-}
-
-function ensureTrailingSlash (str) {
-  return str.charAt(str.length - 1) === '/' ? str : str + '/'
-}
-
-function stripTrailingSlash (str, root = '/') {
-  if (str === '/') return root
-  const lastIdx = str.length - 1
-  return str.charAt(lastIdx) === '/' ? str.substr(0, lastIdx) : str
-}
-
-function regexpEscape (str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // don't escape "-" since it's meaningless in a literal
-}
-