@redpanda-data/docs-extensions-and-macros 5.23.0 → 5.30.0

package/bin/doc-tools.js

@@ -119,7 +119,12 @@ programCli
  *
  * @requirements
  * - Internet connection to access GitHub API
- * - GitHub API rate limits apply (60 requests/hour unauthenticated)
+ * - A GitHub token with access to redpanda-data/streaming-enterprise, which is
+ *   private. Redpanda releases are published there now, and the old public repo
+ *   is frozen, so this command exits rather than report a stale version when it
+ *   has no token. Resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN,
+ *   ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in
+ *   that priority order
  */
 programCli
   .command('get-redpanda-version')
@@ -1057,8 +1062,10 @@ automation
  * @requirements
  * - Python 3.9 or higher
  * - Git
- * - Internet connection to clone Redpanda repository
- * - For --cloud-support: GitHub token with repo permissions (GITHUB_TOKEN env var)
+ * - A GitHub token (resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order) with
+ *   access to redpanda-data/streaming-enterprise, which is private
+ * - Internet connection to clone the streaming-enterprise repository
+ * - For --cloud-support: GitHub token with repo permissions (same resolution chain)
  * - For --cloud-support: Python packages pyyaml and requests
  */
 automation
@@ -1073,7 +1080,8 @@ automation
   .option('--regenerate-old-baseline', 'Re-extract the --diff tag from source instead of using the committed attachments/redpanda-properties-<oldTag>.json baseline')
   .option('--overrides <path>', 'Optional JSON file with property description overrides', 'docs-data/property-overrides.json')
   .option('--output-dir <dir>', 'Where to write all generated files', 'modules/reference')
-  .option('--cloud-support', 'Add AsciiDoc tags to generated property docs to indicate which ones are supported in Redpanda Cloud. This data is fetched from the cloudv2 repository so requires a GitHub token with repo permissions. Set the token as an environment variable using GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN', true)
+  .option('--cloud-support', 'Add AsciiDoc tags to generated property docs to indicate which ones are supported in Redpanda Cloud. This data is fetched from the cloudv2 repository so requires a GitHub token with repo permissions. The token is resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order', true)
+  .option('--no-cloud-support', 'Skip Cloud support tags, and the cloudv2 repository access they need. A GitHub token is still required either way: the extractor clones the private streaming-enterprise repo to read the source')
   .option('--template-property <path>', 'Custom Handlebars template for individual property sections')
   .option('--template-topic-property <path>', 'Custom Handlebars template for topic property sections')
   .option('--template-topic-property-mappings <path>', 'Custom Handlebars template for topic property mappings table')
@@ -1091,17 +1099,35 @@ automation
 
     const newTag = options.tag || options.branch || 'dev'
 
-    if (options.cloudSupport) {
-      console.log('Validating cloud support dependencies...')
-      const { getGitHubToken } = require('../cli-utils/github-token')
-      const token = getGitHubToken()
-      if (!token) {
-        console.error('Error: Cloud support requires a GitHub token')
-        console.error('   Set: export GITHUB_TOKEN=your_token_here')
-        console.error('   Or disable cloud support with: --no-cloud-support')
-        process.exit(1)
+    // Resolved once, via the same priority chain every other GitHub-fetching
+    // command in this CLI already uses (cli-utils/github-token.js) --
+    // notably GIT_CREDENTIALS, which is the token Antora/Netlify builds
+    // actually populate, and which the Makefile's own narrower shell
+    // fallback (REDPANDA_GITHUB_TOKEN/GITHUB_TOKEN/GH_TOKEN only) can't see.
+    // Passed through as GH_TOKEN so the Makefile's clone step picks up
+    // whatever this resolved, private-repo access included, without having
+    // to duplicate the GIT_CREDENTIALS parsing logic in shell.
+    const { getGitHubToken } = require('../cli-utils/github-token')
+    const githubToken = getGitHubToken()
+
+    // A token is required whether or not Cloud metadata is: the extractor
+    // clones the private streaming-enterprise repo to read the source either
+    // way. --no-cloud-support only drops the extra cloudv2 read, so it is not
+    // a remedy for having no token, and pointing at it as one sent people
+    // into a run that got as far as the Makefile's clone step and died there.
+    if (!githubToken) {
+      console.error('Error: Generating property docs requires a GitHub token')
+      console.error('   The extractor reads Redpanda source from the private')
+      console.error('   redpanda-data/streaming-enterprise repository.')
+      console.error('   Set GH_TOKEN, REDPANDA_GITHUB_TOKEN, or GITHUB_TOKEN to a token with access.')
+      if (options.cloudSupport) {
+        console.error('   Cloud support tags (on by default) additionally read the cloudv2 repository;')
+        console.error('   --no-cloud-support skips those, but not the token requirement above.')
       }
-      console.log('Done: GitHub token validated')
+      process.exit(1)
+    }
+    if (options.cloudSupport) {
+      console.log('Done: GitHub token validated for source and cloudv2 access')
     }
 
     let oldTag = options.diff
@@ -1127,6 +1153,7 @@ automation
       console.log(`Building property docs for ${tag}…`)
       const args = ['build', `TAG=${tag}`]
       const env = { ...process.env }
+      if (githubToken) env.GH_TOKEN = githubToken
       if (overrides) env.OVERRIDES = path.resolve(overrides)
       if (options.cloudSupport) env.CLOUD_SUPPORT = '1'
       if (templates.property) env.TEMPLATE_PROPERTY = path.resolve(templates.property)
@@ -1290,8 +1317,9 @@ automation
  *
  * @description
  * Generates comprehensive CLI reference documentation for rpk (Redpanda Keeper).
- * Clones the Redpanda source, builds rpk with Go, and parses `rpk --print-tree` JSON output.
- * Detects Linux-only commands by analyzing Go build tags in the source code.
+ * Clones the Redpanda source from streaming-enterprise (private), builds rpk
+ * with Go, and parses `rpk --print-tree` JSON output. Detects Linux-only
+ * commands by analyzing Go build tags in the source code.
  *
  * Key features:
  * - Clones source from GitHub (sparse checkout for speed)
@@ -1325,6 +1353,9 @@ automation
  * @requirements
  * - Go must be installed (https://go.dev/)
  * - Git must be installed (for cloning source)
+ * - A GitHub token (resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order) with
+ *   access to redpanda-data/streaming-enterprise, which is private (not
+ *   needed when --from-source points at an existing local checkout)
  */
 automation
   .command('rpk-docs')
@@ -1875,7 +1906,7 @@ automation
  *
  * @requirements
  * - GitHub token with access to redpanda-data/cloudv2-infra repository
- * - Token must be set via GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN environment variable
+ * - Token is resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order
  * - Internet connection to access GitHub API
  */
 automation
@@ -2169,7 +2200,9 @@ automation
  * npx doc-tools generate bundle-openapi --tag $VERSION --surface both
  *
  * @requirements
- * - Git to clone Redpanda repository
+ * - Git to clone the streaming-enterprise repository
+ * - A GitHub token (resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order) with
+ *   access to redpanda-data/streaming-enterprise, which is private
  * - Buf tool (automatically installed via npm)
  * - Redocly CLI or vacuum for OpenAPI bundling (automatically detected)
  * - Internet connection to clone repository
@@ -2180,7 +2213,7 @@ automation
   .description('Bundle Redpanda OpenAPI fragments for admin and connect APIs. Requires either --tag or --branch.')
   .option('-t, --tag <tag>', 'Git tag for released content')
   .option('-b, --branch <branch>', 'Branch name for in-progress content')
-  .option('--repo <url>', 'Repository URL', 'https://github.com/redpanda-data/redpanda.git')
+  .option('--repo <url>', 'Repository URL. The default is a private repo, so requires a GitHub token (resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order)', 'https://github.com/redpanda-data/streaming-enterprise.git')
   .addOption(new Option('-s, --surface <surface>', 'Which API surfaces to bundle').choices(['admin', 'connect', 'both']).makeOptionMandatory())
   .option('--out-admin <path>', 'Output path for admin API', 'admin/redpanda-admin-api.yaml')
   .option('--out-connect <path>', 'Output path for connect API', 'connect/redpanda-connect-api.yaml')

package/bin/mcp-tools/versions.js

@@ -74,7 +74,7 @@ function getRedpandaVersion(args = {}) {
       version,
       docker_tag: `docker.redpanda.com/redpandadata/${dockerRepo}:${version}`,
       is_beta: args.beta || false,
-      notes_url: `https://github.com/redpanda-data/redpanda/releases/tag/${version}`,
+      notes_url: `https://github.com/redpanda-data/streaming-enterprise/releases/tag/${version}`,
       _modelRecommendation: 'haiku'
     };
 

package/cli-utils/enterprise-sources.js

@@ -17,13 +17,13 @@ const { getGitHubToken } = require('./github-token')
 const RAW = 'https://raw.githubusercontent.com'
 
 // Repos known to be private, so a 404 can legitimately mean "needs auth".
-// Public sources (redpanda core headers, connect info.csv) 404 only when the
-// file is genuinely missing, and suggesting credentials there sends the
-// reader after a problem that does not exist (e.g. during a transient
-// GitHub blip).
+// Public sources (connect info.csv) 404 only when the file is genuinely
+// missing, and suggesting credentials there sends the reader after a
+// problem that does not exist (e.g. during a transient GitHub blip).
 const PRIVATE_REPO_PREFIXES = [
   `${RAW}/redpanda-data/docs/`,
   `${RAW}/redpanda-data/rp-connect-docs/`,
+  `${RAW}/redpanda-data/streaming-enterprise/`,
 ]
 
 const TOKEN_HINT = ' This source is in a private repository: set GIT_CREDENTIALS (or GITHUB_TOKEN / REDPANDA_GITHUB_TOKEN / ACTIONS_BOT_TOKEN) so the fetch can authenticate.'
@@ -220,8 +220,8 @@ async function loadEnterpriseSources (options, deps = {}) {
   const registryYaml = options.registry
     ? readLocal(options.registry)
     : await fetchText(`${RAW}/redpanda-data/docs/${options.docsRef}/shared/modules/ROOT/partials/enterprise-features.yml`)
-  const coreHeader = await fetchText(`${RAW}/redpanda-data/redpanda/${options.tag}/src/v/features/enterprise_features.h`, 'core enterprise_features.h')
-  const configurationHeader = await fetchText(`${RAW}/redpanda-data/redpanda/${options.tag}/src/v/config/configuration.h`, 'core configuration.h')
+  const coreHeader = await fetchText(`${RAW}/redpanda-data/streaming-enterprise/${options.tag}/src/v/features/enterprise_features.h`, 'core enterprise_features.h')
+  const configurationHeader = await fetchText(`${RAW}/redpanda-data/streaming-enterprise/${options.tag}/src/v/config/configuration.h`, 'core configuration.h')
 
   let connectRef = options.connectRef
   let infoCsv

package/cli-utils/install-test-dependencies.sh

@@ -462,21 +462,73 @@ install_rpk() {
             ;;
     esac
     
-    # Construct download URL and filename
+    # rpk releases now publish to the private redpanda-data/streaming-enterprise,
+    # not the public redpanda-data/redpanda, so a token is required (same
+    # priority order as cli-utils/github-token.js's getGitHubToken(), minus
+    # GIT_CREDENTIALS, which is Antora's own credential store and doesn't
+    # apply to this standalone installer script).
+    local gh_token="${REDPANDA_GITHUB_TOKEN:-${ACTIONS_BOT_TOKEN:-${GITHUB_TOKEN:-${VBOT_GITHUB_API_TOKEN:-${GH_TOKEN:-}}}}}"
+    if [ -z "$gh_token" ]; then
+        log_warn "No GitHub token found (checked REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN)."
+        log_warn "rpk releases are now published to the private redpanda-data/streaming-enterprise repo and require authentication."
+        log_warn "Please install rpk manually:"
+        log_warn "https://docs.redpanda.com/current/get-started/rpk-install/"
+        return 1
+    fi
+
     local rpk_filename="rpk-${rpk_os}-${rpk_arch}.zip"
-    local rpk_url="https://github.com/redpanda-data/redpanda/releases/latest/download/${rpk_filename}"
-    
-    log_info "Detected ${os_name} ${arch_name}, downloading ${rpk_filename}..."
-    
+    local releases_api="https://api.github.com/repos/redpanda-data/streaming-enterprise/releases/latest"
+
+    log_info "Detected ${os_name} ${arch_name}, looking up the latest rpk release..."
+
+    # The Authorization header reaches curl through a config file on stdin
+    # (--config -), never as an -H argument: an argv header is readable by
+    # any process on the host (ps, /proc) for as long as the transfer runs.
+    local release_json
+    if ! release_json=$(curl -fsSL --retry 5 --retry-all-errors \
+            --connect-timeout 30 --max-time 60 --retry-max-time 120 \
+            --config - \
+            -H "Accept: application/vnd.github+json" \
+            "$releases_api" <<EOF
+header = "Authorization: token ${gh_token}"
+EOF
+    ); then
+        log_warn "Failed to query the latest release from streaming-enterprise"
+        log_warn "Please install rpk manually:"
+        log_warn "https://docs.redpanda.com/current/get-started/rpk-install/"
+        return 1
+    fi
+
+    # Resolve the asset's API url (not browser_download_url): only the API
+    # asset endpoint accepts the Authorization header this private repo needs.
+    local rpk_url
+    rpk_url=$(printf '%s' "$release_json" | jq -r --arg name "$rpk_filename" '.assets[] | select(.name == $name) | .url')
+    if [ -z "$rpk_url" ] || [ "$rpk_url" = "null" ]; then
+        log_warn "Latest streaming-enterprise release has no asset named ${rpk_filename}"
+        log_warn "Please install rpk manually:"
+        log_warn "https://docs.redpanda.com/current/get-started/rpk-install/"
+        return 1
+    fi
+
+    log_info "Downloading ${rpk_filename}..."
+
     # Try to download and install rpk.
     # Use -f so HTTP errors (e.g. 403/404/429/503) fail instead of writing an
     # error page into the zip, and retry with curl's default exponential
     # backoff (1s, 2s, 4s, ...) to ride out transient GitHub/CDN and network
     # errors, including rate limits that need time to clear. --retry-max-time
     # caps the whole retry window so CI fails fast on persistent errors.
+    # Accept: application/octet-stream is required on the API asset url to
+    # receive the binary itself instead of its JSON metadata.
+    # Same as the release lookup above: the token travels on stdin, not argv.
     if curl -fL --retry 5 --retry-all-errors \
             --connect-timeout 30 --max-time 300 --retry-max-time 600 \
-            -o "$rpk_filename" "$rpk_url"; then
+            --config - \
+            -H "Accept: application/octet-stream" \
+            -o "$rpk_filename" "$rpk_url" <<EOF
+header = "Authorization: token ${gh_token}"
+EOF
+    then
         if unzip "$rpk_filename" 2>/dev/null; then
             mkdir -p ~/.local/bin
             if mv rpk ~/.local/bin/ 2>/dev/null; then

package/extensions/REFERENCE.adoc

@@ -574,9 +574,35 @@ Responses are classified as follows:
 * 401/403/429: unverifiable — logged at info level, because bot-walled or rate-limited sites are not broken
 * Other statuses, network errors, and timeouts (after one retry): unverifiable — logged as a warning
 
+=== What is not checked
+
+The extension runs at `contentClassified`, on raw AsciiDoc, before Asciidoctor converts anything. Three kinds of URL are therefore left alone, because checking them reports a broken link where the published page has no link at all:
+
+Code blocks::
+URLs inside a listing (`----`), literal (`....`), passthrough (`++++`) or fenced (`+```+`) block. A fenced block counts as one even when the opening delimiter carries a language info string, such as `+```bash+` or `+```yml+`.
+
+Comments::
+URLs on a line comment (`//`) or inside a comment block (`////`). Asciidoctor drops these before rendering, so a generator's provenance note, a Doc Detective test step, or a writer's editorial aside never becomes a link.
+
+Unresolved attribute references::
+A URL still holding a literal `{name}` reference, such as `+https://github.com/{project-github}/issues+`. Attributes are substituted after this hook runs, so the real target is unknown here while the published URL is usually fine. These are logged at info level with the pages that reference them, and counted separately, so a genuinely undefined attribute is still visible.
+
+=== Report attribution
+
+Each finding names the repository, branch, and path the URL was found in, for example:
+
+----
+Broken external link https://example.com/gone (HTTP 404) referenced in: redpanda-data/docs@main:modules/manage/pages/x.adoc
+----
+
+An aggregated site builds the same Antora-relative path from several repositories and many version branches, so a path on its own does not identify a file well enough to act on.
+
 === Environment variables
 
-This extension does not require any environment variables.
+LINK_CHECK::
+Set to `true` to check links. Without it the extension registers and does nothing, so it can live in a playbook that preview builds also use without those builds making network requests.
++
+This is an environment variable rather than a configuration option for two reasons: Antora does not interpolate environment variables into playbook values, and Antora consumes a playbook entry's own `enabled` key itself, before the config reaches the extension, so that name is not available.
 
 === Configuration options
 
@@ -589,6 +615,11 @@ List of regular expressions. When set, only URLs matching at least one pattern a
 exclude (optional)::
 List of regular expressions. URLs matching any pattern are skipped.
 
+versions (optional)::
+Which component versions to check. `latest` checks only each component's latest version, plus every unversioned component; `all` checks every version in the build. Default: `latest`.
++
+A site that publishes many versions of a component republishes the same dead link once per branch, and those older branches are frozen content that nobody edits, so checking them fills the report with findings that cannot be acted on.
+
 concurrency (optional)::
 Number of simultaneous requests. Default: `10`.
 
@@ -598,6 +629,9 @@ Per-request timeout in milliseconds. Default: `10000`.
 fail_on_broken (optional)::
 Log broken links at error level so a build run with `--log-failure-level=error` fails. Default: `false`.
 
+report_file (optional)::
+Path to write a machine-readable JSON report to. Unset by default, in which case no report is written. Written every time the checker runs, including when there is nothing to say, so a consumer polling for this file can tell a clean run apart from one where the checker never ran at all. The report holds `counts`, a `results` array sorted broken-first, and `unresolvedAttributeReferences`; each result carries the URL, its classification and status, and a `refs` array of `{repo, refname, component, version, path}`. Intended for automation that has to act on the findings rather than read them.
+
 === Registration
 
 Register the `external-link-checker` extension in the Antora playbook under the `antora.extensions` key like so:
@@ -607,9 +641,18 @@ Register the `external-link-checker` extension in the Antora playbook under the
 antora:
   extensions:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/external-link-checker'
+      versions: latest
+      report_file: link-check.json
       fail_on_broken: false
 ----
 
+That registration is inert on every build except one run with `LINK_CHECK=true`:
+
+[source,bash]
+----
+LINK_CHECK=true npx antora --fetch antora-playbook.yml
+----
+
 == Validate attributes
 
 This extension ensures the consistency and validity of page attributes, focusing on validating page categories against a predefined list of valid categories and subcategories. It automatically adds missing parent categories for any specified subcategories and removes any specified categories that are invalid. Additionally, it processes specific environment attributes, setting corresponding page-level attributes when environment conditions are met.

package/extensions/external-link-checker.js

@@ -1,5 +1,8 @@
 'use strict'
 
+const fs = require('fs')
+const path = require('path')
+
 const { scanContentUrls } = require('./util/scan-content-urls')
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
 
@@ -20,16 +23,34 @@ const { raiseListenerLimit } = require('./util/raise-listener-limit')
  *       # internal_hostnames: ['docs.redpanda.com']  hosts to skip (default)
  *       # include: []          regex allowlist; when set, only matching URLs are checked
  *       # exclude: []          regex denylist
+ *       # versions: 'latest'   'latest' checks only each component's latest
+ *       #                      version (plus unversioned components); 'all'
+ *       #                      checks every version in the build
  *       # concurrency: 10      simultaneous requests
  *       # timeout: 10000       per-request timeout in ms
  *       # fail_on_broken: false  log broken links at error level so a build
  *       #                        run with --log-failure-level=error fails
+ *       # report_file: ''      path to write a machine-readable JSON report to
+ *
+ * Checking only happens when LINK_CHECK=true is set in the environment, so one
+ * playbook can serve both a scheduled link-check build and ordinary preview
+ * builds, which must not make network requests. It is an environment variable
+ * rather than a config option because Antora does not interpolate environment
+ * variables into playbook values, and because Antora consumes the playbook's
+ * own `enabled` key itself (generator-context.js strips it before the config
+ * reaches an extension), so that name is not available here.
  *
  * Classification:
  * - 2xx/3xx: ok
  * - 404/410: broken (warn, or error with fail_on_broken)
- * - 401/403/429: unverifiable (info) — bot-walled or rate-limited, not broken
+ * - 401/403/429: unverifiable (info) - bot-walled or rate-limited, not broken
  * - other statuses, network errors, timeouts (after one retry): unverifiable (warn)
+ *
+ * Why 'latest' is the default for versions: a site that publishes many
+ * versions of the same component republishes the same dead link once per
+ * branch, and the older branches are frozen content that nobody is going to
+ * edit. Checking them turns the report into a list of findings that cannot be
+ * acted on. Set versions: 'all' to see them anyway.
  */
 
 const USER_AGENT = 'redpanda-docs-link-checker'
@@ -37,59 +58,186 @@ const USER_AGENT = 'redpanda-docs-link-checker'
 module.exports.register = function ({ config = {} }) {
   raiseListenerLimit(this)
   const logger = this.getLogger('external-link-checker-extension')
+  // Inert unless asked for, so this can be registered in a playbook that
+  // preview builds also use. See the note above on why this is an environment
+  // variable and not a config option.
+  if (process.env.LINK_CHECK !== 'true') return
   const internalHostnames = new Set(config.internalHostnames || ['docs.redpanda.com'])
   const include = (config.include || []).map((pattern) => new RegExp(pattern))
   const exclude = (config.exclude || []).map((pattern) => new RegExp(pattern))
+  const versions = config.versions || 'latest'
   const concurrency = config.concurrency || 10
   const timeout = config.timeout || 10000
   const failOnBroken = Boolean(config.failOnBroken)
+  const reportFile = config.reportFile || null
 
   this.on('contentClassified', async ({ contentCatalog }) => {
-    const urlReferences = collectExternalUrls(contentCatalog, { internalHostnames, include, exclude })
-    if (!urlReferences.size) return
-    const counts = { ok: 0, broken: 0, unverifiable: 0 }
-    await runWithConcurrency([...urlReferences.keys()], concurrency, async (url) => {
-      const verdict = await checkUrl(url, { timeout })
-      counts[verdict.classification]++
-      const pages = [...urlReferences.get(url)].join(', ')
-      if (verdict.classification === 'broken') {
-        const message = `Broken external link ${url} (HTTP ${verdict.status}) referenced in: ${pages}`
-        failOnBroken ? logger.error(message) : logger.warn(message)
-      } else if (verdict.classification === 'unverifiable') {
-        const reason = verdict.status ? `HTTP ${verdict.status}` : verdict.reason
-        const log = verdict.status && [401, 403, 429].includes(verdict.status) ? 'info' : 'warn'
-        logger[log](`Could not verify external link ${url} (${reason}) referenced in: ${pages}`)
-      }
+    const { urlReferences, unresolved } = collectExternalUrls(contentCatalog, {
+      internalHostnames,
+      include,
+      exclude,
+      versions,
     })
-    logger.info(
-      `Checked ${urlReferences.size} external links: ${counts.ok} ok, ${counts.broken} broken, ` +
-        `${counts.unverifiable} unverifiable`
-    )
+    // An unresolved attribute reference is not a broken link. This hook runs
+    // before Asciidoctor substitutes attributes, so {latest-operator-version}
+    // is still literal here while the published URL is fine. Report the count
+    // so a genuinely undefined attribute is still visible, but never fetch.
+    if (unresolved.size) {
+      logger.info(
+        `Skipped ${unresolved.size} URL(s) holding an unresolved attribute reference ` +
+          '(attributes are substituted after this hook runs)'
+      )
+      for (const [url, refs] of unresolved) {
+        logger.info(`Unchecked external link ${url} (unresolved attribute) referenced in: ${formatRefs(refs)}`)
+      }
+    }
+    const counts = { ok: 0, broken: 0, unverifiable: 0 }
+    const results = []
+    // Nothing to fetch when every URL was internal, excluded, or an
+    // unresolved attribute reference. Still fall through to writeReport
+    // below: a consumer polling for report_file (the fixer workflow) cannot
+    // tell a clean, nothing-to-check build apart from one where the checker
+    // never ran unless the file always exists when configured.
+    if (urlReferences.size) {
+      await runWithConcurrency([...urlReferences.keys()], concurrency, async (url) => {
+        const verdict = await checkUrl(url, { timeout })
+        counts[verdict.classification]++
+        const refs = urlReferences.get(url)
+        results.push({
+          url,
+          classification: verdict.classification,
+          status: verdict.status ?? null,
+          reason: verdict.reason ?? null,
+          refs: [...refs.values()],
+        })
+        const pages = formatRefs(refs)
+        if (verdict.classification === 'broken') {
+          const message = `Broken external link ${url} (HTTP ${verdict.status}) referenced in: ${pages}`
+          failOnBroken ? logger.error(message) : logger.warn(message)
+        } else if (verdict.classification === 'unverifiable') {
+          const reason = verdict.status ? `HTTP ${verdict.status}` : verdict.reason
+          const log = verdict.status && [401, 403, 429].includes(verdict.status) ? 'info' : 'warn'
+          logger[log](`Could not verify external link ${url} (${reason}) referenced in: ${pages}`)
+        }
+      })
+      logger.info(
+        `Checked ${urlReferences.size} external links: ${counts.ok} ok, ${counts.broken} broken, ` +
+          `${counts.unverifiable} unverifiable`
+      )
+    }
+    if (reportFile) writeReport(reportFile, { results, unresolved, counts, logger })
   })
 }
 
-function collectExternalUrls (contentCatalog, { internalHostnames, include, exclude }) {
+/**
+ * Where a URL was found, in enough detail to act on it: which repository,
+ * which branch, and the path within that repository. A report line carrying
+ * only the Antora-relative path ('modules/reference/pages/x.adoc') is
+ * ambiguous across the several repositories and many version branches an
+ * aggregated site builds from, which makes it unusable for anything that has
+ * to open a pull request against the right one.
+ */
+function fileReference (file) {
+  const src = file.src || {}
+  const origin = src.origin || {}
+  const repo = repoSlug(origin.url)
+  const startPath = origin.startPath || ''
+  const repoPath = startPath ? `${startPath}/${file.path}` : file.path
+  const refname = origin.refname || origin.branch || origin.tag || ''
+  const ref = {
+    repo,
+    refname,
+    component: src.component || '',
+    version: src.version || '',
+    path: repoPath,
+  }
+  // Without origin metadata (a synthetic catalog, or a local content source
+  // with no git remote) the path is all there is to report.
+  const label = repo ? `${repo}${refname ? `@${refname}` : ''}:${repoPath}` : repoPath
+  return { label, ref }
+}
+
+/** 'https://github.com/redpanda-data/docs.git' -> 'redpanda-data/docs' */
+function repoSlug (url) {
+  if (!url || typeof url !== 'string') return ''
+  const match = url.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/)
+  return match ? `${match[1]}/${match[2]}` : ''
+}
+
+function formatRefs (refs) {
+  return [...refs.keys()].join(', ')
+}
+
+/**
+ * Maps each component to its latest version, so non-latest content can be
+ * skipped. Catalogs without getComponents (unit-test doubles) fall back to
+ * checking everything.
+ */
+function latestVersions (contentCatalog) {
+  if (typeof contentCatalog.getComponents !== 'function') return null
+  const latest = new Map()
+  for (const component of contentCatalog.getComponents()) {
+    latest.set(component.name, component.latest ? component.latest.version : '')
+  }
+  return latest
+}
+
+function collectExternalUrls (contentCatalog, { internalHostnames, include, exclude, versions = 'all' }) {
   const urlReferences = new Map()
+  const unresolved = new Map()
+  const latest = versions === 'latest' ? latestVersions(contentCatalog) : null
   const files = contentCatalog
     .getPages((page) => page.out)
     .concat(contentCatalog.findBy({ family: 'partial' }))
   for (const file of files) {
     if (!file.contents) continue
+    const src = file.src || {}
+    // An unversioned component has an empty version and is always current.
+    if (latest && src.version && latest.has(src.component) && latest.get(src.component) !== src.version) continue
+    const { label, ref } = fileReference(file)
     for (const match of scanContentUrls(file.contents.toString())) {
-      let url
-      try {
-        url = new URL(match.url)
-      } catch {
-        continue
+      const target = match.hasAttributeReference ? unresolved : urlReferences
+      if (!match.hasAttributeReference) {
+        let url
+        try {
+          url = new URL(match.url)
+        } catch {
+          continue
+        }
+        if (internalHostnames.has(url.hostname)) continue
+        if (include.length && !include.some((pattern) => pattern.test(match.url))) continue
+        if (exclude.some((pattern) => pattern.test(match.url))) continue
       }
-      if (internalHostnames.has(url.hostname)) continue
-      if (include.length && !include.some((pattern) => pattern.test(match.url))) continue
-      if (exclude.some((pattern) => pattern.test(match.url))) continue
-      if (!urlReferences.has(match.url)) urlReferences.set(match.url, new Set())
-      urlReferences.get(match.url).add(file.path)
+      if (!target.has(match.url)) target.set(match.url, new Map())
+      target.get(match.url).set(label, ref)
     }
   }
-  return urlReferences
+  return { urlReferences, unresolved }
+}
+
+function writeReport (reportFile, { results, unresolved, counts, logger }) {
+  const report = {
+    generatedAt: new Date().toISOString(),
+    counts,
+    // Broken first, then unverifiable, so a consumer reading the head of the
+    // list gets the actionable findings.
+    results: results.sort((a, b) => rank(a.classification) - rank(b.classification) || a.url.localeCompare(b.url)),
+    unresolvedAttributeReferences: [...unresolved].map(([url, refs]) => ({ url, refs: [...refs.values()] })),
+  }
+  try {
+    const dir = path.dirname(reportFile)
+    if (dir && dir !== '.') fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(reportFile, `${JSON.stringify(report, null, 2)}\n`)
+    logger.info(`Wrote link check report to ${reportFile}`)
+  } catch (error) {
+    // The report is an aid for downstream automation; failing the build over
+    // it would hide the link findings the build just produced.
+    logger.warn(`Could not write link check report to ${reportFile}: ${error.message}`)
+  }
+}
+
+function rank (classification) {
+  return classification === 'broken' ? 0 : classification === 'unverifiable' ? 1 : 2
 }
 
 async function checkUrl (url, { timeout, fetchFn = module.exports._fetch }) {
@@ -130,3 +278,4 @@ async function runWithConcurrency (items, limit, task) {
 module.exports._fetch = (...args) => fetch(...args)
 module.exports.checkUrl = checkUrl
 module.exports.collectExternalUrls = collectExternalUrls
+module.exports.repoSlug = repoSlug

package/extensions/url-to-xref.js

@@ -483,6 +483,11 @@ function convertContent (content, resolverContext) {
       continue
     }
     if (!hostnames.has(url.hostname) || match.inAttributeEntry || match.inAttributeValue) continue
+    // The path still holds a literal {attribute} reference: attributes are
+    // substituted after this hook, so the real target is unknown here. It
+    // cannot be looked up in the catalog, and reporting it as unmatched would
+    // be wrong when the substituted URL resolves fine.
+    if (match.hasAttributeReference) continue
     if (ignore.some((pattern) => pattern.test(url.pathname))) continue
     // An xref target cannot carry a query string, and dropping one would
     // change the link: the docs UI reads parameters such as