@redpanda-data/docs-extensions-and-macros 5.7.0 → 5.8.0

package/bin/doc-tools.js

@@ -1660,6 +1660,21 @@ automation
             return match
           }
         })
+      // Antora resolves page metadata with a header-only parse that stops at
+      // the first blank line. The chart README templates emit :description:
+      // below the title's blank line, so the page shipped the generic site
+      // meta description despite carrying one (found on k-connect-helm-spec,
+      // DOC-2414 investigation). Relocate the first :description: into the
+      // header, directly under the title.
+      const descMatch = doc.match(/^:description:[^\n]*$/m)
+      if (descMatch) {
+        const headerEnd = doc.indexOf('\n\n')
+        if (headerEnd !== -1 && doc.indexOf(descMatch[0]) > headerEnd) {
+          doc = doc.replace(descMatch[0] + '\n', '')
+          doc = doc.replace(/^(= .+)$/m, `$1\n${descMatch[0]}`)
+          doc = doc.replace(/\n{3,}/g, '\n\n')
+        }
+      }
       fs.writeFileSync(outFile, doc, 'utf8')
 
       console.log(`Done: Wrote ${outFile}`)

package/extensions/add-faq-structured-data.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 /**
  * Generates FAQPage JSON-LD structured data for SEO.
  *
@@ -147,6 +149,7 @@ function generateFaqJsonLd(faqs, baseUrl) {
 }
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('add-faq-structured-data-extension')
   let playbook
 

package/extensions/add-git-dates.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 /**
  * Adds Git commit dates to pages as attributes.
  *
@@ -179,6 +181,7 @@ async function getTreeFiles (git, gitdir, oid, prefix, cache, treeCache) {
 }
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('add-git-dates-extension')
   const context = this
 

package/extensions/add-global-attributes.js

@@ -1,3 +1,4 @@
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 /* Example use in the playbook
 * antora:
     extensions:
@@ -12,6 +13,7 @@ const _ = require('lodash');
 const ATTRIBUTES_PATH = 'modules/ROOT/partials/';  // Default path within the 'shared' component
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('global-attributes-extension');
 
   /**

package/extensions/add-llms-directive.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 /**
  * Adds llms.txt directive to HTML pages for agent-friendly documentation.
  *
@@ -16,6 +18,7 @@
 const { formatLlmsDirective } = require('../extension-utils/llms-utils')
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('add-llms-directive-extension')
 
   this.on('pagesComposed', ({ contentCatalog }) => {

package/extensions/add-markdown-urls-to-sitemap.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 /**
  * Adds markdown URL entries to sitemap.xml files for AI-friendly documentation.
  *
@@ -21,6 +23,7 @@ const { parseStringPromise } = require('xml2js')
 const { toMarkdownUrl } = require('../extension-utils/url-utils')
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('add-markdown-urls-to-sitemap-extension')
 
   this.on('beforePublish', async ({ siteCatalog }) => {

package/extensions/add-pages-to-root.js

@@ -1,4 +1,6 @@
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   this.on('beforePublish', ({ siteCatalog, contentCatalog }) => {
     const logger = this.getLogger('add-pages-to-site-root');
     if (!config || !config.files || !config.files.length) {

package/extensions/aggregate-terms.js

@@ -1,3 +1,4 @@
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 /* Example use in the playbook
 * antora:
     extensions:
@@ -10,6 +11,7 @@ const path = require('path');
 const TERMS_PATH = 'modules/terms/partials/';  // Default path within the 'shared' component
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('term-aggregation-extension');
 
   /**

package/extensions/algolia-indexer/index.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const generateIndex = require('./generate-index')
+const { raiseListenerLimit } = require('../util/raise-listener-limit')
 const algoliasearch = require('algoliasearch')
 const http = require('http')
 const https = require('https')
@@ -21,6 +22,7 @@ function register ({
     ...unknownOptions
   }
 }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('algolia-indexer-extension')
 
   // Validate required environment variables

package/extensions/archive-attachments.js

@@ -1,3 +1,4 @@
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 "use strict";
 
 const fs = require("fs");
@@ -35,6 +36,7 @@ async function createTarInMemory(tempDir) {
 }
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger("archive-attachments-extension");
   const archives = config.data?.archives || [];
 

package/extensions/collect-bloblang-samples.js

@@ -1,6 +1,8 @@
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 const yaml = require('js-yaml');
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('collect-bloblang-samples');
 
   this.on('contentClassified', ({ contentCatalog }) => {

package/extensions/compute-end-of-life.js

@@ -1,8 +1,11 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const calculateEOL = require('./util/calculate-eol.js');
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   this.on('contentClassified', ({ contentCatalog }) => {
     const logger = this.getLogger("compute-end-of-life-extension");
 

package/extensions/conditional-home-redirect.js

@@ -8,7 +8,10 @@
 
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('conditional-home-redirect')
   let shouldRedirect = false
 

package/extensions/convert-llms-to-txt.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const { toMarkdownUrl } = require('../extension-utils/url-utils');
 const { stripMarkdownMetadata } = require('../extension-utils/llms-utils');
 
@@ -20,6 +22,7 @@ const { stripMarkdownMetadata } = require('../extension-utils/llms-utils');
  * Must run after convert-to-markdown extension to access page.markdownContents.
  */
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('convert-llms-to-txt-extension');
   let siteUrl = '';
 

package/extensions/convert-to-markdown.js

@@ -1,3 +1,4 @@
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 const path = require('path')
 const os = require('os')
 const yaml = require('js-yaml')
@@ -187,6 +188,7 @@ function generateFrontmatter(page) {
 }
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('convert-to-markdown-extension')
   let playbook
 

package/extensions/find-related-docs.js

@@ -1,6 +1,9 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('related-docs-extension');
 
   this.on('documentsConverted', async ({ contentCatalog, siteCatalog }) => {

package/extensions/find-related-labs.js

@@ -1,6 +1,9 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('related-labs-extension');
 
   this.on('documentsConverted', async ({ contentCatalog, siteCatalog }) => {

package/extensions/generate-fields-only-pages.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
@@ -121,6 +123,7 @@ const DEFAULTS = {
 }
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('generate-fields-only-pages-extension')
 
   // Merge config with defaults

package/extensions/generate-index-data.js

@@ -1,7 +1,10 @@
 'use strict';
+
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 const _ = require('lodash');
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('generate-index-data-extension');
 
   this.on('documentsConverted', async ({ contentCatalog, siteCatalog }) => {

package/extensions/generate-rp-connect-categories.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 /**
  * Redpanda Connect Category Aggregation Extension
  *
@@ -11,6 +13,7 @@
  * Ensure generate-rp-connect-info is listed BEFORE this extension in your playbook.
  */
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('redpanda-connect-category-aggregation-extension')
 
   this.on('contentClassified', ({ contentCatalog }) => {

package/extensions/generate-rp-connect-info.js

@@ -1,4 +1,6 @@
 'use strict'
+
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
 const fs = require('fs')
 const path = require('path')
 const Papa = require('papaparse')
@@ -11,6 +13,7 @@ const DEFAULTS = {
 }
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('redpanda-connect-info-extension')
   const { getAntoraValue } = require('../cli-utils/antora-utils')
 

package/extensions/git-full-clone.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const { execSync } = require('child_process')
 const fs = require('fs')
 const path = require('path')
@@ -33,6 +35,7 @@ const { getGitHubToken } = require('../cli-utils/github-token')
  */
 
 module.exports.register = function ({ config, playbook }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('git-full-clone-extension')
 
   logger.info('✓ git-full-clone extension loaded')

package/extensions/modify-connect-tag-playbook.js

@@ -1,8 +1,11 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const GetLatestConnectTag = require('./version-fetcher/get-latest-connect');
 
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('modify-connect-tag-playbook-extension');
 
   this.on('contextStarted', async ({ playbook }) => {

package/extensions/process-context-switcher.js

@@ -17,7 +17,10 @@
 
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('context-switcher-extension');
 
   this.on('documentsConverted', async ({ contentCatalog }) => {

package/extensions/produce-redirects.js

@@ -1,11 +1,14 @@
 '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({

package/extensions/replace-attributes-in-attachments.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const semver = require('semver');
 const micromatch = require('micromatch');
 const formatVersion = require('./util/format-version.js');
@@ -24,6 +26,7 @@ const sanitize = require('./util/sanitize-attributes.js');
  *         - ...
  */
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('replace-attributes-extension');
   const replacements = config.data?.replacements || [];
 

package/extensions/resolve-xrefs-in-attachments.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 /**
  * Resolves AsciiDoc xrefs in JSON attachment files to HTML links.
  *
@@ -19,6 +21,7 @@
  */
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('resolve-xrefs-in-attachments')
 
   this.on('contentClassified', ({ contentCatalog }) => {

package/extensions/set-available-attachment-versions.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const semver = require('semver')
 
 /**
@@ -34,6 +36,7 @@ const PROPERTIES_JSON_RX = /^redpanda-properties-(v\d+\.\d+\.\d+(?:-[\w.]+)?)\.j
 const CONNECT_JSON_RX = /^connect-(\d+\.\d+\.\d+(?:-[\w.]+)?)\.json$/
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('set-available-attachment-versions-extension')
 
   this.once('contentClassified', ({ contentCatalog }) => {

package/extensions/unified-navigation.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const yaml = require('js-yaml')
 
 /**
@@ -35,6 +37,7 @@ const yaml = require('js-yaml')
  */
 
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('unified-navigation-extension')
 
   this.on('navigationBuilt', ({ contentCatalog }) => {

package/extensions/unlisted-pages.js

@@ -1,6 +1,9 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const { addToNavigation, unlistedPagesHeading = 'Unlisted Pages' } = config;
   const logger = this.getLogger('unlisted-pages-extension');
 

package/extensions/unpublish-pages.js

@@ -1,6 +1,9 @@
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function () {
+  raiseListenerLimit(this)
   const logger = this.getLogger('unpublish-pages-extension');
 
   this.on('documentsConverted', ({ siteCatalog, contentCatalog }) => {

package/extensions/util/raise-listener-limit.js

@@ -0,0 +1,28 @@
+'use strict'
+
+// Antora's GeneratorContext is one shared EventEmitter for every registered
+// extension, and Redpanda playbooks register enough of them that per-event
+// listener counts legitimately exceed Node's default threshold of 10. Node
+// then prints MaxListenersExceededWarning ("Possible EventEmitter memory
+// leak detected. 11 contentClassified listeners added to [GeneratorContext]")
+// in build logs even though each extension adds exactly one listener per
+// event per build.
+//
+// Every extension in this package raises the limit before subscribing, so
+// the suppression holds no matter which subset of extensions a playbook
+// registers or in what order. The cap is bounded rather than unlimited (0)
+// to keep Node's leak detection meaningful for pathological cases.
+const GENERATOR_CONTEXT_MAX_LISTENERS = 64
+
+function raiseListenerLimit (context) {
+  if (
+    typeof context.getMaxListeners === 'function' &&
+    typeof context.setMaxListeners === 'function' &&
+    context.getMaxListeners() !== 0 &&
+    context.getMaxListeners() < GENERATOR_CONTEXT_MAX_LISTENERS
+  ) {
+    context.setMaxListeners(GENERATOR_CONTEXT_MAX_LISTENERS)
+  }
+}
+
+module.exports = { raiseListenerLimit, GENERATOR_CONTEXT_MAX_LISTENERS }

package/extensions/validate-attributes.js

@@ -6,7 +6,10 @@
 
 'use strict';
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('attribute-validation-extension');
 
   this.on('documentsConverted', async ({ contentCatalog, siteCatalog }) => {

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

@@ -1,6 +1,9 @@
 'use strict';
 
+const { raiseListenerLimit } = require('../util/raise-listener-limit')
+
 module.exports.register = function ({ config }) {
+  raiseListenerLimit(this)
   const GetLatestRedpandaVersion = require('./get-latest-redpanda-version');
   const GetLatestConsoleVersion = require('./get-latest-console-version');
   const GetLatestDockerTag = require('./fetch-latest-docker-tag');

package/package.json

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

package/tools/redpanda-connect/generate-rpcn-connector-docs.js

@@ -55,7 +55,10 @@ function mergeOverrides(target, overrides) {
     throw new Error('Target must be a valid object');
   }
 
-  const scalarKeys = ['description', 'type', 'annotated_field', 'version'];
+  // 'summary' earns its place here the hard way: overrides.json has carried
+  // summary overrides (zmq4, ffi) that were silently dropped because the key
+  // fell through every branch below. Summaries feed page meta descriptions.
+  const scalarKeys = ['description', 'summary', 'type', 'annotated_field', 'version'];
 
   for (const key in overrides) {
     // === Handle annotated_options ===
@@ -674,17 +677,120 @@ async function generateRpcnConnectorDocs(options) {
     }
   }
 
+  // Self-heal published page headers: pages are one-time drafts, so pages
+  // created before the template emitted :description: never got one.
+  let descriptionBackfill = { backfilled: [], skippedNoSummary: [] };
+  if (!writeFullDrafts) {
+    descriptionBackfill = backfillPageDescriptions(dataObj);
+  }
+
   return {
     partialsWritten,
     draftsWritten,
     partialFiles,
     draftFiles,
-    lostSectionWarnings
+    lostSectionWarnings,
+    descriptionBackfill
   };
 }
 
+
+// Connector page families that have per-component pages under
+// modules/components/pages/. Other data keys (config, bloblang-functions,
+// bloblang-methods) have no per-component page to backfill.
+const PAGE_TYPE_DIRS = new Set([
+  'inputs', 'outputs', 'processors', 'caches', 'buffers', 'metrics',
+  'tracers', 'scanners', 'rate-limits', 'rate_limits'
+]);
+
+/**
+ * Insert a tagged :description: into existing connector page headers that
+ * lack one, sourced from the component's summary in the connector data.
+ *
+ * Connector pages are one-time first drafts: pages drafted before the
+ * template emitted :description: never got one, and nothing rewrote them,
+ * so hundreds of published pages ship the generic site meta description
+ * even though ~97% of components carry a summary in the source data. This
+ * runs on every generation, so the page set self-heals and stays healed.
+ *
+ * The inserted block matches the connector template's shape: the meta tag
+ * region lets single-source stubs inherit the description as a header
+ * attribute (see the template comment in connector.hbs).
+ *
+ * @param {Object} connectorData - Parsed connector data (typed arrays)
+ * @param {Object} [options]
+ * @param {string} [options.pagesRoot] - Pages directory (default: modules/components/pages under cwd)
+ * @param {boolean} [options.dryRun] - Report without writing
+ * @returns {{backfilled: string[], skippedNoSummary: string[]}}
+ */
+function backfillPageDescriptions (connectorData, { pagesRoot, dryRun = false } = {}) {
+  const root = pagesRoot || path.resolve(process.cwd(), 'modules/components/pages');
+  const results = { backfilled: [], skippedNoSummary: [] };
+  if (!fs.existsSync(root)) return results;
+
+  for (const [dataKey, items] of Object.entries(connectorData)) {
+    if (!PAGE_TYPE_DIRS.has(dataKey) || !Array.isArray(items)) continue;
+    // The data uses 'rate-limits' while the pages directory is
+    // 'rate_limits'. Resolve whichever spelling exists on disk.
+    const typeDir = fs.existsSync(path.join(root, dataKey))
+      ? dataKey
+      : dataKey.replace(/-/g, '_');
+    for (const item of items) {
+      if (!item || !item.name) continue;
+      const pagePath = path.join(root, typeDir, `${item.name}.adoc`);
+      if (!fs.existsSync(pagePath)) continue;
+
+      const content = fs.readFileSync(pagePath, 'utf8');
+      const lines = content.split('\n');
+      const headerEnd = lines.findIndex((l) => l.trim() === '');
+      const header = lines.slice(0, headerEnd === -1 ? lines.length : headerEnd);
+      if (header.some((l) => l.startsWith(':description:'))) continue;
+
+      // Meta descriptions are read as plain text by search results, link
+      // previews, and assistants, so flatten AsciiDoc markup mechanically:
+      // xrefs and links become their labels, inline code loses its
+      // backticks. No prose is edited.
+      const summary = (item.summary || '')
+        .replace(/(?:xref|link):[^\[\]]+\[([^\]]*)\]/g, '$1')
+        // Bare URL macros (no xref:/link: prefix) and internal xref shorthand
+        // also appear in source summaries and render literally if left in place.
+        .replace(/https?:\/\/[^\s\[\]]+\[([^\]]*)\]/g, '$1')
+        .replace(/<<[^,>]+,([^>]+)>>/g, '$1')
+        .replace(/<<([^>]+)>>/g, '$1')
+        // Strip the "open in new tab" caret that AsciiDoc URL macros carry
+        // inside the link text, e.g. [Open Telemetry collector^].
+        .replace(/\^/g, '')
+        .replace(/`([^`]*)`/g, '$1')
+        .replace(/\s+/g, ' ')
+        .trim();
+      if (!summary) {
+        results.skippedNoSummary.push(`${typeDir}/${item.name}`);
+        continue;
+      }
+
+      const insertAt = headerEnd === -1 ? lines.length : headerEnd;
+      lines.splice(insertAt, 0, '// tag::meta[]', `:description: ${summary}`, '// end::meta[]');
+      if (!dryRun) fs.writeFileSync(pagePath, lines.join('\n'), 'utf8');
+      results.backfilled.push(`${typeDir}/${item.name}`);
+    }
+  }
+
+  if (results.backfilled.length) {
+    console.log(`Backfilled :description: into ${results.backfilled.length} connector page header(s) from source summaries`);
+  }
+  if (results.skippedNoSummary.length) {
+    console.warn(
+      `\u26a0 ${results.skippedNoSummary.length} connector page(s) lack both a header description and a source summary: ` +
+      results.skippedNoSummary.join(', ') +
+      '. Author these in the overrides file or upstream.'
+    );
+  }
+  return results;
+}
+
 module.exports = {
   generateRpcnConnectorDocs,
+  backfillPageDescriptions,
   mergeOverrides,
   resolveReferences
 };

package/tools/redpanda-connect/templates/bloblang-functions-overview.hbs

@@ -1,6 +1,8 @@
 = Bloblang Functions
 // tag::single-source[]
+// tag::meta[]
 :description: A list of Bloblang functions
+// end::meta[]
 
 // © 2024 Redpanda Data Inc.
 

package/tools/redpanda-connect/templates/bloblang-methods-overview.hbs

@@ -1,6 +1,8 @@
 = Bloblang Methods
 // tag::single-source[]
+// tag::meta[]
 :description: A list of Bloblang methods
+// end::meta[]
 
 // © 2024 Redpanda Data Inc.
 

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

@@ -3,7 +3,19 @@
 :type: {{type}}
 {{#if support}}:support: {{support}}{{/if}}
 :categories: [{{join categories ", "}}]
-:description: {{#if summary}}{{{summary}}}{{else if description}}{{description}}{{else}}// TODO: Missing description. Add a description in the overrides file or source data.{{/if}}
+{{#if summary}}
+// tag::meta[]
+:description: {{{summary}}}
+// end::meta[]
+{{else if description}}
+// tag::meta[]
+:description: {{description}}
+// end::meta[]
+{{/if}}
+{{!-- No fallback line when neither exists: an emitted TODO would become
+     the attribute VALUE and stubs would inherit it into their meta tags.
+     Missing descriptions are the tracked editorial backlog
+     (cloud-docs .github/description-allowlist.txt). --}}
 
 component_type_dropdown::[]
 

package/tools/rpk-docs/generate-plugin-stubs.js

@@ -23,7 +23,7 @@ const { spawnSync } = require('child_process')
  * authoritative: dashified filenames cannot be reversed unambiguously
  * (rpk-ai-llm-provider could be `llm provider` or `llm-provider`).
  * @param {string} partialsDir - Directory of generated .adoc partials
- * @returns {Array<{file: string, title: string, description: string|undefined}>} Sorted by command path
+ * @returns {Array<{file: string, title: string, description: string|undefined, hasMetaTag: boolean}>} Sorted by command path
  */
 function readPartialTitles(partialsDir) {
   const partials = []
@@ -35,11 +35,18 @@ function readPartialTitles(partialsDir) {
       console.warn(`Warning: no title line in ${file}; skipping`)
       continue
     }
-    // The partial repeats :description: inside its single-source tag, but
-    // Antora resolves page metadata with a header-only parse that never sees
-    // the include — the stub must carry the description in its own header.
+    // Antora resolves page metadata with a header-only parse that never
+    // sees the body include, so the stub must carry the description in its
+    // own header. Partials generated with doc-tools >= 5.4 carry a nested
+    // meta tag region around :description: that stubs include dynamically;
+    // older partials fall back to a literal copy of the header description.
     const description = (content.match(/^:description:[ \t]*(.+)$/m) || [])[1]
-    partials.push({ file, title: match[1].trim(), description: description && description.trim() })
+    partials.push({
+      file,
+      title: match[1].trim(),
+      description: description && description.trim(),
+      hasMetaTag: content.includes('tag::meta['),
+    })
   }
   // Hierarchical order: sort by command words so parents precede children
   partials.sort((a, b) => {
@@ -121,11 +128,23 @@ function inferIncludePrefix(stubDir, plugin) {
  * @param {string} [params.description] - Meta description from the partial header
  * @param {string} params.includePrefix - Antora resource prefix
  * @param {Array<string>} params.attributes - Page attribute lines
+ * @param {boolean} [params.hasMetaTag] - Partial carries a tag::meta[] region (doc-tools >= 5.4)
  * @returns {string}
  */
-function renderStub({ title, file, description, includePrefix, attributes }) {
+function renderStub({ title, file, description, includePrefix, attributes, hasMetaTag }) {
   const lines = [`= ${title}`]
-  if (description) lines.push(`:description: ${description}`)
+  // The description mechanism is always the first header line after the
+  // title: a header include for partials with a meta tag region, or a
+  // literal copy as the fallback for partials generated before 5.4. Antora
+  // resolves page metadata with a header-only parse that stops at the first
+  // blank line, so either form must sit above it — an include below the
+  // blank line is never evaluated for attributes and the page ships the
+  // generic site description.
+  if (hasMetaTag) {
+    lines.push(`include::${includePrefix}${file}[tag=meta]`)
+  } else if (description) {
+    lines.push(`:description: ${description}`)
+  }
   for (const attr of attributes) lines.push(attr)
   lines.push('')
   lines.push(`include::${includePrefix}${file}[tag=single-source]`)
@@ -162,6 +181,7 @@ function reconcileStubs({
   const existingStubs = fs.readdirSync(stubDir).filter(f => f.endsWith('.adoc'))
 
   const created = []
+  const upgraded_ = []
   const deleted = []
   const keptNonStub = []
   const skippedAliasTargets = []
@@ -206,7 +226,34 @@ function reconcileStubs({
     fs.existsSync(stubDir) ? fs.readdirSync(stubDir).filter(f => f.endsWith('.adoc')) : []
   )
   for (const partial of partials) {
-    if (remainingStubs.has(partial.file)) continue
+    if (remainingStubs.has(partial.file)) {
+      // Existing stub: upgrade it in place when the partial has gained the
+      // meta tag region and the stub does not yet include it. The header
+      // include is what lets the stub inherit :description: as page
+      // metadata, so upgrading here makes the consumer repo self-heal on
+      // the next sync instead of needing a hand-written migration PR.
+      if (partial.hasMetaTag && !dryRun) {
+        const stubPath = path.join(stubDir, partial.file)
+        const stubContent = fs.readFileSync(stubPath, 'utf8')
+        if (!stubContent.includes('[tag=meta]')) {
+          const metaInclude = `include::${includePrefix}${partial.file}[tag=meta]`
+          // A later attribute entry overrides an earlier one (verified
+          // empirically against an Antora build), so a literal
+          // :description: below the include would win and leave the
+          // include dead weight. These are generated reference stubs, so
+          // any literal is a static backfill the include supersedes:
+          // strip it. Hand-maintained prose stubs never pass through this
+          // reconciler, so intentionally curated descriptions are safe.
+          let upgraded = stubContent.replace(/^:description: .*\n/m, '')
+          upgraded = upgraded.replace(/^(= .+)$/m, `$1\n${metaInclude}`)
+          if (upgraded !== stubContent) {
+            fs.writeFileSync(stubPath, upgraded, 'utf8')
+            upgraded_.push(partial.file)
+          }
+        }
+      }
+      continue
+    }
     if (aliasClaims.has(partial.file)) {
       skippedAliasTargets.push({ file: partial.file, claimedBy: aliasClaims.get(partial.file) })
       continue
@@ -285,7 +332,7 @@ function reconcileStubs({
     }
   }
 
-  return { created, deleted, keptNonStub, navUpdated, renameCandidates, skippedAliasTargets }
+  return { created, upgraded: upgraded_, deleted, keptNonStub, navUpdated, renameCandidates, skippedAliasTargets }
 }
 
 module.exports = {

package/tools/rpk-docs/templates/command.hbs

@@ -6,7 +6,12 @@
      page at worst. Availability pages are excluded from cloud by not
      generating a stub for them in cloud-docs. --}}
 = {{commandPath}}
+{{!-- Comment lines are legal inside an AsciiDoc header, so the meta tag
+     region can wrap the page's single description. Stub pages inherit it
+     with a header include (see the note at the single-source tag). --}}
+// tag::meta[]
 :description: {{{wrapDescriptionPassthrough shortDesc}}}
+// end::meta[]
 {{#if pageAliases}}
 :page-aliases: {{{pageAliases}}}
 {{/if}}
@@ -23,11 +28,24 @@
 {{/each}}
 
 // tag::single-source[]
-:description: {{{wrapDescriptionPassthrough shortDesc}}}
-{{!-- The description attribute is repeated inside the tagged region so
-     single-sourcing consumers (stub pages that include this tag) inherit
-     the meta description. page-aliases and page-platforms deliberately stay
-     outside the tag: consumers must not inherit alias registrations. --}}
+{{!-- Stub pages inherit this page's description by including the header's
+     meta tag region as a HEADER attribute. A stub that only includes
+     tag=single-source after a blank line never gets it: Antora resolves
+     page metadata with a header-only parse that stops at the stub's first
+     blank line, so the include is never evaluated for attributes and the
+     page ships the generic site description (verified empirically,
+     2026-08-05, including that a headerless include destroys the body).
+     The working stub shape is two includes:
+
+       = Page title
+       include::...page.adoc[tag=meta]        <- header: no blank line above
+                                              <- blank line ends the header
+       include::...page.adoc[tag=single-source]
+
+     Earlier revisions repeated :description: inside this region on the
+     wrong belief that it reached stub metadata by itself; it never did.
+     page-aliases and page-platforms deliberately stay outside both tag
+     regions: consumers must not inherit alias registrations. --}}
 {{!-- Deprecation notice --}}
 {{#if deprecated}}
 [CAUTION]