@redpanda-data/docs-extensions-and-macros 5.3.7 → 5.7.1

package/cli-utils/github-token.js

@@ -5,19 +5,68 @@
  * Supports multiple common token variable names with priority order.
  */
 
+/**
+ * Extract a GitHub token from the GIT_CREDENTIALS environment variable.
+ *
+ * GIT_CREDENTIALS is the variable Antora's own credential manager reads, so in
+ * Antora builds (for example, Netlify) it is the source guaranteed to hold a
+ * working credential for private content sources. Entries follow the git
+ * credential store format and may be separated by commas or newlines:
+ *
+ *   https://<token>:@github.com
+ *   https://<username>:<password>@github.com
+ *   https://x-access-token:<token>@github.com
+ *
+ * @param {string} [credentials] - Credential contents (defaults to process.env.GIT_CREDENTIALS)
+ * @returns {string|null} GitHub token or null if no github.com entry found
+ */
+function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
+  if (!credentials) return null;
+
+  for (const entry of credentials.split(/[,\n]/)) {
+    const match = entry.trim().match(/^https?:\/\/([^@]+)@([^/]+)/);
+    // Exact host match (optional port) so entries for lookalike hosts such as
+    // github.com.evil.example or notgithub.com are never treated as GitHub.
+    if (!match || !/^github\.com(:\d+)?$/i.test(match[2])) continue;
+
+    const [username, ...passwordParts] = match[1].split(':');
+    const password = passwordParts.join(':');
+
+    // Token may sit in the username position (https://TOKEN:@github.com) or,
+    // when a username such as x-access-token is present, in the password position.
+    const token = password || username;
+    if (!token) continue;
+
+    try {
+      return decodeURIComponent(token);
+    } catch (err) {
+      return token;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Get GitHub token from environment variables
  * Checks multiple common variable names in priority order:
- * 1. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
- * 2. ACTIONS_BOT_TOKEN - GitHub Actions bot token
- * 3. GITHUB_TOKEN - GitHub Actions default
- * 4. VBOT_GITHUB_API_TOKEN - Legacy bot token
- * 5. GH_TOKEN - GitHub CLI default
+ * 1. GIT_CREDENTIALS - Antora's credential store contents (github.com entry)
+ * 2. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
+ * 3. ACTIONS_BOT_TOKEN - GitHub Actions bot token
+ * 4. GITHUB_TOKEN - GitHub Actions default
+ * 5. VBOT_GITHUB_API_TOKEN - Legacy bot token
+ * 6. GH_TOKEN - GitHub CLI default
+ *
+ * Note: this resolver feeds both git clone/fetch auth and GitHub API clients
+ * (Octokit). Wherever GIT_CREDENTIALS is set (for example, Antora builds on
+ * Netlify), API calls authenticate with that same token, whose API scopes may
+ * differ from the token env vars it outranks.
  *
  * @returns {string|null} GitHub token or null if not found
  */
 function getGitHubToken() {
-  return process.env.REDPANDA_GITHUB_TOKEN ||
+  return getTokenFromGitCredentials() ||
+         process.env.REDPANDA_GITHUB_TOKEN ||
          process.env.ACTIONS_BOT_TOKEN ||
          process.env.GITHUB_TOKEN ||
          process.env.VBOT_GITHUB_API_TOKEN ||
@@ -57,6 +106,7 @@ function hasGitHubToken() {
 
 module.exports = {
   getGitHubToken,
+  getTokenFromGitCredentials,
   getAuthenticatedGitHubUrl,
   hasGitHubToken
 };

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,8 +1,11 @@
 'use strict'
 
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
 const { execSync } = require('child_process')
 const fs = require('fs')
 const path = require('path')
+const { getGitHubToken } = require('../cli-utils/github-token')
 
 /**
  * Configure Antora to use full git clones instead of shallow clones.
@@ -32,6 +35,7 @@ const path = require('path')
  */
 
 module.exports.register = function ({ config, playbook }) {
+  raiseListenerLimit(this)
   const logger = this.getLogger('git-full-clone-extension')
 
   logger.info('✓ git-full-clone extension loaded')
@@ -66,6 +70,30 @@ module.exports.register = function ({ config, playbook }) {
     let unshallowedCount = 0
     const unshallowTimeout = config?.unshallowTimeout || 60000 // Default 60 seconds per repo
 
+    // Private repos need credentials: the git CLI does not share Antora's
+    // built-in credential manager, so resolve a token (GIT_CREDENTIALS first,
+    // then the common token env vars) and hand it to git through a credential
+    // helper. Both the config and the token travel via environment variables
+    // (GIT_CONFIG_* and GIT_FULL_CLONE_TOKEN), so nothing touches the command
+    // line, the remote URL, or the cached .git/config, and there is no shell
+    // quoting to break on other platforms. Config entry 0 clears any inherited
+    // helpers; entry 1 registers a helper scoped to github.com so no other
+    // host is ever offered the token.
+    const token = getGitHubToken()
+    const gitCommand = 'git fetch --unshallow'
+    const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+    if (token) {
+      logger.info('  → Using GitHub token for unshallow fetches')
+      gitEnv.GIT_FULL_CLONE_TOKEN = token
+      gitEnv.GIT_CONFIG_COUNT = '2'
+      gitEnv.GIT_CONFIG_KEY_0 = 'credential.helper'
+      gitEnv.GIT_CONFIG_VALUE_0 = ''
+      gitEnv.GIT_CONFIG_KEY_1 = 'credential.https://github.com.helper'
+      gitEnv.GIT_CONFIG_VALUE_1 = '!f() { echo "username=x-access-token"; echo "password=$GIT_FULL_CLONE_TOKEN"; }; f'
+    } else {
+      logger.info('  → No GitHub token found; unshallow may fail for private repos')
+    }
+
     for (const aggregate of contentAggregate) {
       for (const origin of aggregate.origins || []) {
         const gitdir = origin.gitdir
@@ -80,11 +108,11 @@ module.exports.register = function ({ config, playbook }) {
             logger.info(`  → Unshallowing ${path.basename(gitdir)}...`)
 
             // Use git fetch --unshallow to convert to full clone
-            execSync('git fetch --unshallow', {
+            execSync(gitCommand, {
               cwd: gitdir,
               stdio: 'pipe',
               timeout: unshallowTimeout,
-              env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+              env: gitEnv
             })
 
             const duration = Date.now() - startTime

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.3.7",
+  "version": "5.7.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",