@redpanda-data/docs-extensions-and-macros 5.9.0 → 5.10.0

package/bin/doc-tools.js

@@ -34,7 +34,6 @@ const {
 // Import other utilities
 const { determineDocsBranch } = require('../cli-utils/self-managed-docs-branch.js')
 const fetchFromGithub = require('../tools/fetch-from-github.js')
-const { urlToXref } = require('../cli-utils/convert-doc-links.js')
 const { getAntoraValue, setAntoraValue } = require('../cli-utils/antora-utils')
 
 // --------------------------------------------------------------------
@@ -1677,47 +1676,8 @@ automation
       r = spawnSync('pandoc', [md, '-t', 'asciidoc', '-o', outFile], { stdio: 'inherit' })
       if (r.status !== 0) process.exit(r.status)
 
-      let doc = fs.readFileSync(outFile, 'utf8')
-      const xrefRe = /https:\/\/docs\.redpanda\.com[^\s\]\[\)"]+(?:\[[^\]]*\])?/g
-      doc = doc
-        .replace(/(\[\d+\])\]\./g, '$1\\].')
-        .replace(/(\[\d+\])\]\]/g, '$1\\]\\]')
-        .replace(/^=== +(https?:\/\/[^\[]*)\[([^\]]*)\]/gm, '=== link:++$1++[$2]')
-        .replace(/^== # (.*)$/gm, '= $1')
-        .replace(/^== description: (.*)$/gm, ':description: $1')
-        .replace(xrefRe, (match) => {
-          let urlPart = match
-          let bracketPart = ''
-          const m = match.match(/^([^\[]+)(\[[^\]]*\])$/)
-          if (m) {
-            urlPart = m[1]
-            bracketPart = m[2]
-          }
-          if (urlPart.endsWith('#')) return match
-          try {
-            const xref = urlToXref(urlPart)
-            return bracketPart ? `${xref}${bracketPart}` : `${xref}[]`
-          } catch (err) {
-            console.warn(`⚠️ urlToXref failed on ${urlPart}: ${err.message}`)
-            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')
+      const { formatHelmSpec } = require('../cli-utils/format-helm-spec')
+      fs.writeFileSync(outFile, formatHelmSpec(fs.readFileSync(outFile, 'utf8')), 'utf8')
 
       console.log(`Done: Wrote ${outFile}`)
     }
@@ -1989,26 +1949,8 @@ automation
       process.exit(1)
     }
 
-    let doc = fs.readFileSync(opts.output, 'utf8')
-    const xrefRe = /https:\/\/docs\.redpanda\.com[^\s\]\[\)"]+(?:\[[^\]]*\])?/g
-    doc = doc.replace(xrefRe, (match) => {
-      let urlPart = match
-      let bracketPart = ''
-      const m = match.match(/^([^\[]+)(\[[^\]]*\])$/)
-      if (m) {
-        urlPart = m[1]
-        bracketPart = m[2]
-      }
-      if (urlPart.endsWith('#')) return match
-      try {
-        const xref = urlToXref(urlPart)
-        return bracketPart ? `${xref}${bracketPart}` : `${xref}[]`
-      } catch (err) {
-        console.warn(`⚠️ urlToXref failed on ${urlPart}: ${err.message}`)
-        return match
-      }
-    })
-    fs.writeFileSync(opts.output, doc, 'utf8')
+    // docs.redpanda.com URLs are left as-is: the url-to-xref Antora
+    // extension converts them to validated xrefs at site build time.
 
     if (tmpSrc) fs.rmSync(tmpSrc, { recursive: true, force: true })
     fs.rmSync(configTmp, { recursive: true, force: true })

package/cli-utils/format-helm-spec.js

@@ -0,0 +1,58 @@
+'use strict'
+
+/**
+ * Cleans up the AsciiDoc that pandoc produces from a chart's helm-docs README
+ * so that it renders correctly as a docs page.
+ *
+ * docs.redpanda.com URLs are deliberately left as they are: the url-to-xref
+ * Antora extension converts them to validated xrefs at site build time.
+ */
+function formatHelmSpec (doc) {
+  const formatted = doc
+    // pandoc escapes footnote-style references inconsistently
+    .replace(/(\[\d+\])\]\./g, '$1\\].')
+    .replace(/(\[\d+\])\]\]/g, '$1\\]\\]')
+    // a section title that is a bare URL has to be a link macro to render
+    .replace(/^=== +(https?:\/\/[^[]*)\[([^\]]*)\]/gm, '=== link:++$1++[$2]')
+    .replace(/^== # (.*)$/gm, '= $1')
+    .replace(/^== description: (.*)$/gm, ':description: $1')
+    // helm-docs prints each chart dependency's repository verbatim into the
+    // Requirements table, and charts in the redpanda-operator monorepo refer
+    // to their subcharts by local path (for example the Redpanda chart's
+    // console dependency, repository: file://../../console/chart).
+    // Asciidoctor auto-links a bare file:// URL, which publishes a link that
+    // can never resolve for a reader, so render these as literal code.
+    .replace(/(^|[^`])(file:\/\/[^\s|\]`]+)/gm, '$1`$2`')
+
+  return relocateDescriptionIntoHeader(formatted)
+}
+
+/**
+ * Moves the first `:description:` attribute up into the document header.
+ *
+ * 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 of its own (found on k-connect-helm-spec, DOC-2414).
+ *
+ * The conversion above turns `== description:` into the attribute but leaves it
+ * where pandoc put it, so the move has to happen after it.
+ *
+ * @param {string} doc - AsciiDoc source.
+ * @returns {string} Source with the description in the header.
+ */
+function relocateDescriptionIntoHeader (doc) {
+  const descMatch = doc.match(/^:description:[^\n]*$/m)
+  if (!descMatch) return doc
+
+  const headerEnd = doc.indexOf('\n\n')
+  // Already inside the header, so there is nothing to move.
+  if (headerEnd === -1 || doc.indexOf(descMatch[0]) < headerEnd) return doc
+
+  return doc
+    .replace(descMatch[0] + '\n', '')
+    .replace(/^(= .+)$/m, `$1\n${descMatch[0]}`)
+    .replace(/\n{3,}/g, '\n\n')
+}
+
+module.exports = { formatHelmSpec }

package/extensions/README.adoc

@@ -89,6 +89,10 @@ IMPORTANT: Extensions must be registered under the `antora.extensions` key in yo
 * **set-available-attachment-versions** - Point UI templates at the newest generated JSON attachments that exist in the catalog
 * **validate-attributes** - Validate AsciiDoc attributes
 
+=== Link health
+* **url-to-xref** - Convert docs.redpanda.com URLs in content into validated xrefs and warn about URLs that match no published page
+* **external-link-checker** - Verify external URLs respond and report dead links in the build log
+
 === AI-friendly documentation
 * **convert-to-markdown** - Export documentation pages as markdown with frontmatter
 * **convert-llms-to-txt** - Generate llms.txt and component-specific exports for AI agents

package/extensions/REFERENCE.adoc

@@ -485,6 +485,97 @@ antora:
     - require: '@redpanda-data/docs-extensions-and-macros/extensions/set-available-attachment-versions'
 ----
 
+== URL to xref
+
+This extension converts absolute docs.redpanda.com URLs found in page and partial content into Antora xrefs, using the content catalog as the single source of truth. A URL is converted only when it maps to a page that is actually published in the current build, so the extension never guesses at URL structure. Converted links are validated by Antora's own xref resolution, and internal URLs that match no published page are logged as warnings — which makes this extension a broken-internal-link detector for the whole site.
+
+Behavior details:
+
+* Runs at `contentClassified`, before AsciiDoc conversion, so emitted xrefs flow through Antora's normal resolution and broken-xref logging.
+* URLs inside listing, literal, fenced, and passthrough blocks, inline code spans, attribute entry lines, and macro attribute values (such as `link=` on an image macro) are left untouched.
+* Legacy URL shapes (`/docs/...`, `/current/...`, `/vX.Y/...`, and pre-rename component slugs such as `/redpanda-connect/`) are rewritten to candidate paths, but a candidate is only used when it matches a published page.
+* Fragments (`#anchor`) and link labels are preserved, including a label that a generator wrapped across a line break, whose line breaks are collapsed to single spaces.
+* An unlabeled URL becomes `xref:...[]` so that Antora fills in the target page title. An unlabeled URL that carries a fragment is given link text explicitly, because Antora cannot resolve a section title and would render the raw resource ID as the link text: the extension uses the heading the fragment points at, falls back to the target page title, and leaves the URL as a raw link if it can read neither. Heading ids are also read from the partials a target page includes, because the reference pages that hold most anchor targets are thin wrappers around generated partials.
+* Targets in the latest version of a component emit an unversioned xref; targets pinned to an older version emit `version@component:module:page`.
+* A URL that points at a page's former path resolves through the `page-aliases` attribute that the page declares. Antora does not register those aliases as catalog files until it converts documents, which is after this extension runs, so the extension reads them from the page header. Only aliases in the same component and version as the page that declares them are mapped.
+* A URL that carries a query string is left as a raw link, because an xref cannot express one and dropping it would change the link (for example `?platform=kubernetes`, which the UI reads to preselect a tab). These are reported at info level, not as warnings.
+* Builds that publish the latest version under its real version number instead of a symbolic segment (such as this repository's preview build) still resolve `/current/...` URLs, so the same content works in both.
+
+=== Environment variables
+
+This extension does not require any environment variables.
+
+=== Configuration options
+
+hostnames (optional)::
+List of hostnames treated as internal documentation URLs. Default: `['docs.redpanda.com']`.
+
+ignore (optional)::
+List of regular expressions matched against URL paths. Matching URLs are left untouched with no warning. Use this for paths on the docs domain that live outside the Antora catalog. Default: `['^/api/', '^/mcp(/|$)']` (the API reference is hosted by Bump.sh, and `/mcp` is the docs MCP server endpoint).
+
+log_unconverted (optional)::
+Whether to log a warning for each internal URL that matches no published page. Default: `true`.
+
+=== Registration
+
+Register the `url-to-xref` extension in the Antora playbook under the `antora.extensions` key like so:
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/url-to-xref'
+----
+
+== External link checker
+
+This extension collects every external http(s) URL referenced in page and partial content and verifies that it responds, reporting dead links in the build log. Internal links are covered by the url-to-xref extension plus Antora's own xref validation; this extension covers everything that points off-site.
+
+Because it performs network requests, register it only in builds where that belongs (for example a scheduled nightly build), not necessarily on every preview build.
+
+Responses are classified as follows:
+
+* 2xx/3xx: ok
+* 404/410: broken — logged as a warning, or at error level with `fail_on_broken`
+* 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
+
+=== Environment variables
+
+This extension does not require any environment variables.
+
+=== Configuration options
+
+internal_hostnames (optional)::
+Hostnames to skip because they are internal documentation URLs. Default: `['docs.redpanda.com']`.
+
+include (optional)::
+List of regular expressions. When set, only URLs matching at least one pattern are checked.
+
+exclude (optional)::
+List of regular expressions. URLs matching any pattern are skipped.
+
+concurrency (optional)::
+Number of simultaneous requests. Default: `10`.
+
+timeout (optional)::
+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`.
+
+=== Registration
+
+Register the `external-link-checker` extension in the Antora playbook under the `antora.extensions` key like so:
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/extensions/external-link-checker'
+      fail_on_broken: false
+----
+
 == 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

@@ -0,0 +1,132 @@
+'use strict'
+
+const { scanContentUrls } = require('./util/scan-content-urls')
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
+/**
+ * External Link Checker Extension
+ *
+ * Collects every external http(s) URL referenced in page and partial content
+ * and verifies it responds, reporting dead links in the build log. Internal
+ * links are covered by the url-to-xref extension plus Antora's own xref
+ * validation; this extension covers everything that points off-site.
+ *
+ * Because it performs network requests, register it only where that belongs
+ * (for example a nightly build), not necessarily on every preview build:
+ *
+ * antora:
+ *   extensions:
+ *     - require: '@redpanda-data/docs-extensions-and-macros/extensions/external-link-checker'
+ *       # internal_hostnames: ['docs.redpanda.com']  hosts to skip (default)
+ *       # include: []          regex allowlist; when set, only matching URLs are checked
+ *       # exclude: []          regex denylist
+ *       # 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
+ *
+ * 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
+ * - other statuses, network errors, timeouts (after one retry): unverifiable (warn)
+ */
+
+const USER_AGENT = 'redpanda-docs-link-checker'
+
+module.exports.register = function ({ config = {} }) {
+  raiseListenerLimit(this)
+  const logger = this.getLogger('external-link-checker-extension')
+  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 concurrency = config.concurrency || 10
+  const timeout = config.timeout || 10000
+  const failOnBroken = Boolean(config.failOnBroken)
+
+  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}`)
+      }
+    })
+    logger.info(
+      `Checked ${urlReferences.size} external links: ${counts.ok} ok, ${counts.broken} broken, ` +
+        `${counts.unverifiable} unverifiable`
+    )
+  })
+}
+
+function collectExternalUrls (contentCatalog, { internalHostnames, include, exclude }) {
+  const urlReferences = new Map()
+  const files = contentCatalog
+    .getPages((page) => page.out)
+    .concat(contentCatalog.findBy({ family: 'partial' }))
+  for (const file of files) {
+    if (!file.contents) continue
+    for (const match of scanContentUrls(file.contents.toString())) {
+      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 (!urlReferences.has(match.url)) urlReferences.set(match.url, new Set())
+      urlReferences.get(match.url).add(file.path)
+    }
+  }
+  return urlReferences
+}
+
+async function checkUrl (url, { timeout, fetchFn = module.exports._fetch }) {
+  let lastError
+  for (const attempt of [{ method: 'HEAD' }, { method: 'GET' }, { method: 'GET', retry: true }]) {
+    try {
+      const response = await fetchFn(url, {
+        method: attempt.method,
+        redirect: 'follow',
+        headers: { 'user-agent': USER_AGENT },
+        signal: AbortSignal.timeout(timeout),
+      })
+      const status = response.status
+      // HEAD rejected or unsupported: many CDNs and bot walls refuse HEAD
+      // (403, 404, ...) but answer GET normally, so confirm any HEAD failure
+      // with GET before classifying
+      if (attempt.method === 'HEAD' && status >= 400) continue
+      if (status < 400) return { classification: 'ok', status }
+      if (status === 404 || status === 410) return { classification: 'broken', status }
+      return { classification: 'unverifiable', status }
+    } catch (error) {
+      lastError = error
+      if (attempt.retry) break
+    }
+  }
+  return { classification: 'unverifiable', status: null, reason: lastError ? lastError.message : 'request failed' }
+}
+
+async function runWithConcurrency (items, limit, task) {
+  const queue = [...items]
+  const workers = Array.from({ length: Math.min(limit, queue.length) }, async () => {
+    while (queue.length) await task(queue.shift())
+  })
+  await Promise.all(workers)
+}
+
+// Indirection so tests can stub the HTTP layer without a network.
+module.exports._fetch = (...args) => fetch(...args)
+module.exports.checkUrl = checkUrl
+module.exports.collectExternalUrls = collectExternalUrls

package/extensions/url-to-xref.js

@@ -0,0 +1,515 @@
+'use strict'
+
+const { scanContentUrls } = require('./util/scan-content-urls')
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
+/**
+ * URL to Xref Extension
+ *
+ * Converts absolute docs-site URLs (for example https://docs.redpanda.com/...)
+ * found in page and partial content into Antora xrefs, using the content
+ * catalog as the single source of truth. A URL is only converted when it maps
+ * to a page that is actually published in this build — the extension never
+ * guesses at URL structure. Converted links get Antora's build-time xref
+ * validation; internal URLs that match no published page are reported as
+ * warnings, which makes this extension a broken-internal-link detector.
+ *
+ * Registration (docs-site playbook):
+ *
+ * antora:
+ *   extensions:
+ *     - require: '@redpanda-data/docs-extensions-and-macros/extensions/url-to-xref'
+ *       # hostnames: ['docs.redpanda.com']   (default)
+ *       # log_unconverted: true              (default)
+ *
+ * Behavior details:
+ * - Runs at contentClassified, before AsciiDoc conversion, so emitted xrefs
+ *   flow through Antora's normal resolution and broken-xref logging.
+ * - URLs inside listing/literal/fenced/passthrough blocks, inline code spans,
+ *   attribute entry lines, and macro attribute values (link=...) are left
+ *   untouched.
+ * - Legacy URL shapes (/docs/..., /current/..., /vX.Y/..., pre-rename
+ *   component slugs) are rewritten to candidate paths, but a candidate is
+ *   only used when it matches a published page.
+ * - Fragments (#anchor) and link labels are preserved, including labels that a
+ *   generator wrapped across a line break. An unlabeled URL becomes xref:...[]
+ *   so Antora fills in the target page title, except when it carries a
+ *   fragment, where link text has to be supplied (see linkTextFor).
+ * - Targets in the latest version of a component emit an unversioned xref;
+ *   targets pinned to an older version emit version@component:module:page.
+ * - URLs pointing at a page's former path resolve through the page-aliases the
+ *   page declares (see buildUrlMap).
+ * - URLs carrying a query string are left raw, because an xref cannot express
+ *   one; they are reported at info level rather than as warnings.
+ */
+
+// Rewrites for URL shapes that predate the current docs.redpanda.com site
+// structure. Every produced candidate is verified against the catalog before
+// use, so an entry that no longer applies is harmless. Slugs mirror the live
+// site's 301 redirects.
+const LEGACY_SLUG_REWRITES = {
+  'redpanda-connect': 'connect',
+  'redpanda-cloud': 'cloud-data-platform',
+  'redpanda-labs': 'labs',
+}
+
+// The component that serves the pre-umbrella site's unprefixed URLs
+// (/docs/..., /current/..., /vX.Y/...). The live site 301s those to
+// /streaming/....
+const LEGACY_UNPREFIXED_COMPONENT = 'streaming'
+
+module.exports.register = function ({ config = {} }) {
+  raiseListenerLimit(this)
+  const logger = this.getLogger('url-to-xref-extension')
+  const hostnames = new Set(config.hostnames || ['docs.redpanda.com'])
+  const logUnconverted = config.logUnconverted !== false
+  // URL paths that live on the docs domain but outside the Antora catalog: the
+  // API reference is hosted by Bump.sh, and /mcp is the docs MCP server
+  // endpoint. Left untouched, no warning.
+  const ignore = (config.ignore || ['^/api/', '^/mcp(/|$)']).map((pattern) => new RegExp(pattern))
+
+  this.on('contentClassified', ({ playbook, contentCatalog }) => {
+    const resolverContext = Object.assign(buildUrlMap(contentCatalog), {
+      hostnames,
+      ignore,
+      latestVersionSegment: (playbook.urls || {}).latestVersionSegment || 'current',
+      // Used to read heading ids out of the partials a target page includes.
+      resolveInclude: (spec, page) => contentCatalog.resolveResource(spec, page.src, 'partial', ['partial', 'page']),
+    })
+    let convertedCount = 0
+    const unmapped = new Map()
+    const withQueryString = new Set()
+    const withoutLinkText = new Set()
+    const files = contentCatalog
+      .getPages((page) => page.out)
+      .concat(contentCatalog.findBy({ family: 'partial' }))
+    for (const file of files) {
+      if (!file.contents) continue
+      const result = convertContent(file.contents.toString(), resolverContext)
+      if (result.converted) {
+        file.contents = Buffer.from(result.content)
+        convertedCount += result.converted
+      }
+      for (const url of result.unmapped) {
+        if (!unmapped.has(url)) unmapped.set(url, new Set())
+        unmapped.get(url).add(file.path)
+      }
+      for (const url of result.withQueryString) withQueryString.add(url)
+      for (const url of result.withoutLinkText) withoutLinkText.add(url)
+    }
+    if (logUnconverted) {
+      for (const [url, pages] of unmapped) {
+        logger.warn(`No published page matches ${url} (found in: ${[...pages].join(', ')})`)
+      }
+    }
+    if (withQueryString.size) {
+      logger.info(
+        `Left ${withQueryString.size} docs URL${withQueryString.size === 1 ? '' : 's'} with a query string as raw ` +
+          `link${withQueryString.size === 1 ? '' : 's'} (an xref cannot carry one): ${[...withQueryString].join(', ')}`
+      )
+    }
+    if (withoutLinkText.size) {
+      logger.info(
+        `Left ${withoutLinkText.size} docs URL${withoutLinkText.size === 1 ? '' : 's'} with a fragment as raw ` +
+          `link${withoutLinkText.size === 1 ? '' : 's'} (no link text could be resolved from the target page): ` +
+          `${[...withoutLinkText].join(', ')}`
+      )
+    }
+    if (convertedCount || unmapped.size) {
+      logger.info(
+        `Converted ${convertedCount} docs URL${convertedCount === 1 ? '' : 's'} to xrefs; ` +
+          `${unmapped.size} URL${unmapped.size === 1 ? '' : 's'} matched no published page`
+      )
+    }
+  })
+}
+
+/**
+ * Builds a lookup of published URL path -> resource coordinates from the
+ * content catalog. Covers regular pages, the synthetic alias files Antora
+ * registers during classification for component start pages and the site start
+ * page (so component landing URLs like /connect/ and the site root resolve),
+ * and the page-aliases each page declares in its header.
+ *
+ * page-aliases have to be read from the page header here because Antora does
+ * not register them as catalog alias files until it converts documents, which
+ * is after this extension runs. Without them, a URL that points at a page's
+ * former path (the majority of the raw URLs in generated Helm and CRD specs)
+ * would be reported as broken even though the site redirects it.
+ */
+function buildUrlMap (contentCatalog) {
+  const components = {}
+  for (const component of contentCatalog.getComponents()) {
+    components[component.name] = { latestVersion: component.latest ? component.latest.version : '' }
+  }
+  const isLatest = (name, version) => name in components && components[name].latestVersion === version
+  // The target file travels with the entry so that link text can be resolved
+  // from it later, which an xref with a fragment needs (see linkTextFor).
+  const toEntry = ({ component, version, module: module_, relative }, page) => ({
+    component,
+    version,
+    module: module_,
+    relative,
+    latest: isLatest(component, version),
+    page,
+  })
+  const urls = new Map()
+  const pages = contentCatalog.getPages((p) => p.out && p.pub && p.pub.url)
+  for (const page of pages) {
+    urls.set(normalizeUrlPath(page.pub.url), toEntry(page.src, page))
+  }
+  for (const alias of contentCatalog.findBy({ family: 'alias' })) {
+    if (!alias.pub || !alias.pub.url || alias.pub.splat) continue
+    let target = alias.rel
+    let depth = 0
+    while (target && target.src && target.src.family === 'alias' && depth++ < 5) target = target.rel
+    if (!target || !target.src || target.src.family !== 'page' || !target.pub) continue
+    const key = normalizeUrlPath(alias.pub.url)
+    if (!urls.has(key)) urls.set(key, toEntry(target.src, target))
+  }
+  for (const page of pages) {
+    for (const key of pageAliasUrls(page)) {
+      if (!urls.has(key)) urls.set(key, toEntry(page.src, page))
+    }
+  }
+  return { urls, components }
+}
+
+const PAGE_ALIASES_ATTRIBUTE = ':page-aliases:'
+
+/**
+ * Returns the raw value of a page's page-aliases attribute, joining the
+ * continuation lines that AsciiDoc allows a long value to span.
+ */
+function extractPageAliases (header) {
+  const lines = header.split('\n')
+  const start = lines.findIndex((line) => line.startsWith(PAGE_ALIASES_ATTRIBUTE))
+  if (start === -1) return
+  let value = lines[start].slice(PAGE_ALIASES_ATTRIBUTE.length)
+  for (let index = start; value.trimEnd().endsWith('\\') && index + 1 < lines.length; index++) {
+    value = `${value.trimEnd().slice(0, -1)} ${lines[index + 1]}`
+  }
+  return value
+}
+
+/**
+ * Returns the normalized URL paths that a page's page-aliases attribute makes
+ * available. Only aliases in the same component and version as the target page
+ * are mapped, because their URL is derived from the target page's own
+ * published URL; a cross-component or cross-version alias is left to Antora's
+ * own redirect handling.
+ */
+function pageAliasUrls (page) {
+  const contents = page.contents && page.contents.toString()
+  if (!contents) return []
+  const aliases = extractPageAliases(contents.slice(0, 4096))
+  if (!aliases) return []
+  const targetUrl = normalizeUrlPath(page.pub.url)
+  const targetSuffix = pageUrlSuffix(page.src)
+  // The alias URL differs from the target URL only in the module and page
+  // segments, so everything before them is a shared prefix.
+  if (targetSuffix && !targetUrl.endsWith(`/${targetSuffix}`)) return []
+  const base = targetSuffix ? targetUrl.slice(0, -(targetSuffix.length + 1)) : targetUrl
+  const keys = []
+  for (const spec of aliases.split(',')) {
+    const aliasSrc = parsePageAliasSpec(spec, page.src)
+    if (!aliasSrc) continue
+    const suffix = pageUrlSuffix(aliasSrc)
+    keys.push(normalizeUrlPath(suffix ? `${base}/${suffix}` : base || '/'))
+  }
+  return keys
+}
+
+/**
+ * Returns the module and page portion of a page's URL, which is the part that
+ * follows the component and version segments. A module named ROOT and an
+ * index page contribute no segment of their own.
+ */
+function pageUrlSuffix ({ module: module_, relative }) {
+  let stem = relative.replace(/\.adoc$/, '')
+  if (stem === 'index') stem = ''
+  else if (stem.endsWith('/index')) stem = stem.slice(0, -'/index'.length)
+  const segments = []
+  if (module_ && module_ !== 'ROOT') segments.push(module_)
+  if (stem) segments.push(stem)
+  return segments.join('/')
+}
+
+/**
+ * Parses one page-aliases entry ([version@][component:][module:]relative) into
+ * a resource id, inheriting anything it leaves out from the page that declares
+ * it. Returns undefined for an entry that names another component or version.
+ */
+function parsePageAliasSpec (spec, targetSrc) {
+  let rest = spec.trim()
+  if (!rest) return
+  const versionSeparator = rest.indexOf('@')
+  if (versionSeparator !== -1) {
+    if (rest.slice(0, versionSeparator) !== targetSrc.version) return
+    rest = rest.slice(versionSeparator + 1)
+  }
+  const parts = rest.split(':')
+  if (parts.length > 3) return
+  const relative = parts.pop()
+  if (!relative) return
+  const module_ = parts.length ? parts.pop() : targetSrc.module
+  if (parts.length && parts[0] !== targetSrc.component) return
+  // Antora still accepts an alias spec without the file extension.
+  return { module: module_ || targetSrc.module, relative: relative.endsWith('.adoc') ? relative : `${relative}.adoc` }
+}
+
+/** Normalizes a URL path for map lookup: drops the query string, an
+ * index.html or .html suffix, and any trailing slash (except the bare root).
+ */
+function normalizeUrlPath (urlPath) {
+  let result = urlPath.split('?')[0]
+  if (result.endsWith('/index.html')) result = result.slice(0, -'index.html'.length)
+  else if (result.endsWith('.html')) result = result.slice(0, -'.html'.length)
+  if (result.length > 1 && result.endsWith('/')) result = result.slice(0, -1)
+  return result || '/'
+}
+
+/**
+ * Produces lookup candidates for a normalized path: the path itself, legacy
+ * rewrites, and an explicit-latest-version -> symbolic-segment swap. Callers
+ * must verify each candidate against the URL map.
+ */
+function candidatePaths (normalizedPath, { components, latestVersionSegment }) {
+  const candidates = [normalizedPath]
+  let unprefixed = normalizedPath
+  const docsPrefix = unprefixed.match(/^\/docs(\/.*)?$/)
+  if (docsPrefix) unprefixed = docsPrefix[1] || '/'
+  const versionPrefix = unprefixed.match(/^\/(?:current|beta|v?(\d+\.\d+(?:\.\d+)?))(\/.*)?$/)
+  if (versionPrefix) {
+    const [, version, rest = ''] = versionPrefix
+    candidates.push(`/${LEGACY_UNPREFIXED_COMPONENT}/${version || latestVersionSegment}${rest}`)
+    if (version) candidates.push(`/${LEGACY_UNPREFIXED_COMPONENT}/${latestVersionSegment}${rest}`)
+    // Builds without a symbolic latest-version segment (for example preview
+    // builds) publish the latest version under its real version number, and
+    // may drop the component segment entirely (ROOT component). Substitute
+    // each component's latest version; only verified candidates are used.
+    if (!version) {
+      for (const [name, { latestVersion }] of Object.entries(components)) {
+        if (!latestVersion) continue
+        candidates.push(`/${latestVersion}${rest}`)
+        candidates.push(`/${name}/${latestVersion}${rest}`)
+      }
+    }
+  } else if (docsPrefix) {
+    const rest = unprefixed === '/' ? '' : unprefixed
+    candidates.push(`/${LEGACY_UNPREFIXED_COMPONENT}/${latestVersionSegment}${rest}`)
+    for (const [name, { latestVersion }] of Object.entries(components)) {
+      if (!latestVersion) continue
+      candidates.push(`/${latestVersion}${rest}`)
+      candidates.push(`/${name}/${latestVersion}${rest}`)
+    }
+  }
+  for (const [slug, componentName] of Object.entries(LEGACY_SLUG_REWRITES)) {
+    if (normalizedPath === `/${slug}` || normalizedPath.startsWith(`/${slug}/`)) {
+      candidates.push(`/${componentName}${normalizedPath.slice(slug.length + 1)}`)
+    }
+  }
+  const segments = normalizedPath.split('/')
+  const component = components[segments[1]]
+  if (component && segments[2]) {
+    const version = segments[2].replace(/^v/, '')
+    if (version === component.latestVersion) {
+      // An explicitly versioned URL whose version is the component's latest is
+      // published under the symbolic segment instead (redirect:to strategy).
+      candidates.push(['', segments[1], latestVersionSegment, ...segments.slice(3)].join('/'))
+    } else if (segments[2] === latestVersionSegment && component.latestVersion) {
+      // The reverse: a symbolic latest-version URL in a build that publishes
+      // the latest version under its real number (for example the preview
+      // site, which sets no latest-version segment).
+      candidates.push(['', segments[1], component.latestVersion, ...segments.slice(3)].join('/'))
+    }
+  }
+  return candidates
+}
+
+function resolveUrlPath (urlPath, resolverContext) {
+  for (const candidate of candidatePaths(normalizeUrlPath(urlPath), resolverContext)) {
+    const entry = resolverContext.urls.get(candidate)
+    if (entry) return entry
+  }
+  return undefined
+}
+
+function entryToXref (entry, fragment, label) {
+  const versionPrefix = entry.latest || !entry.version ? '' : `${entry.version}@`
+  return `xref:${versionPrefix}${entry.component}:${entry.module}:${entry.relative}${fragment || ''}[${label || ''}]`
+}
+
+// Parsed heading id -> heading text, cached per target file.
+const headingsByFile = new WeakMap()
+const EXPLICIT_ANCHOR_PATTERNS = [
+  /^\[\[([\w:.-]+)(?:,.*)?\]\]$/,
+  /^\[#([\w:.-]+)(?:[,.].*)?\]$/,
+  /^\[id="?([\w:.-]+)"?(?:,.*)?\]$/,
+]
+const HEADING_RX = /^(={1,6})\s+(\S.*)$/
+
+/**
+ * Returns the link text for a converted URL, or undefined when the URL should
+ * be left alone.
+ *
+ * A labeled URL keeps its label, and an unlabeled URL without a fragment gets
+ * empty text so that Antora fills in the target page title. An unlabeled URL
+ * *with* a fragment has to be given text explicitly: Antora cannot resolve a
+ * section title, so `xref:page.adoc#anchor[]` renders the raw resource id as
+ * the link text. Prefer the heading the fragment points at, then the page
+ * title; if neither can be read, the caller leaves the URL as a raw link,
+ * which still displays sensibly.
+ */
+function linkTextFor (label, fragment, page, resolveInclude) {
+  if (label) return label
+  if (!fragment) return ''
+  const contents = page && page.contents && page.contents.toString()
+  if (!contents) return undefined
+  let headings = headingsByFile.get(page)
+  if (!headings) headingsByFile.set(page, (headings = pageHeadingIds(contents, page, resolveInclude)))
+  return headings.get(fragment.slice(1)) || documentTitle(contents)
+}
+
+// Only the first level of includes is followed, and only this many per page:
+// enough for the reference pages that assemble a partial per category, without
+// walking an include tree of unknown depth.
+const MAX_INCLUDES_SEARCHED = 50
+
+/**
+ * Collects the heading ids of a page plus those of the partials it includes.
+ * The reference pages that carry most anchor targets are thin wrappers around
+ * generated partials — every property heading on the cluster and broker
+ * property pages lives in one — and Antora has not resolved includes yet at
+ * contentClassified, so they are resolved here.
+ */
+function pageHeadingIds (contents, page, resolveInclude) {
+  const ids = parseHeadingIds(contents)
+  if (!resolveInclude) return ids
+  let searched = 0
+  for (const match of contents.matchAll(/^include::([^[\s]+)\[/gm)) {
+    if (++searched > MAX_INCLUDES_SEARCHED) break
+    let included
+    try {
+      included = resolveInclude(match[1], page)
+    } catch {
+      continue
+    }
+    if (!included || !included.contents) continue
+    for (const [id, text] of parseHeadingIds(included.contents.toString())) {
+      if (!ids.has(id)) ids.set(id, text)
+    }
+  }
+  return ids
+}
+
+/**
+ * Maps every heading id in a page to its text, covering explicit anchors
+ * ([[id]], [#id], [id=...]) and the ids Asciidoctor generates from heading
+ * text. Id generation is approximated: a mismatch only costs the page-title
+ * fallback.
+ */
+function parseHeadingIds (contents) {
+  const ids = new Map()
+  let pendingId
+  for (const rawLine of contents.split('\n')) {
+    const line = rawLine.trim()
+    const anchor = EXPLICIT_ANCHOR_PATTERNS.reduce((found, pattern) => found || pattern.exec(line), null)
+    if (anchor) {
+      pendingId = anchor[1]
+      continue
+    }
+    const heading = HEADING_RX.exec(line)
+    if (heading) {
+      const text = sanitizeLinkText(heading[2])
+      const id = pendingId || autoId(text)
+      if (id && text && !ids.has(id)) ids.set(id, text)
+    }
+    if (line) pendingId = undefined
+  }
+  return ids
+}
+
+/** Returns a page's document title (its level-0 heading), sanitized. */
+function documentTitle (contents) {
+  const match = /^=\s+(\S.*)$/m.exec(contents)
+  return match ? sanitizeLinkText(match[1]) : undefined
+}
+
+/**
+ * Makes text safe to use as an xref label: an unbalanced bracket would end the
+ * macro early, and a nested link macro cannot appear inside one.
+ */
+function sanitizeLinkText (text) {
+  return text
+    .replace(/(?:xref|link|image):[^[\s]*\[([^\]]*)\]/g, '$1')
+    .replace(/[[\]]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/** Approximates Asciidoctor id generation with idprefix='' and idseparator='-'. */
+function autoId (text) {
+  return text
+    .replace(/[`*+#^~]/g, '')
+    .toLowerCase()
+    .replace(/[^\w\- .]/g, '')
+    .trim()
+    .replace(/[ .]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * Rewrites every mappable docs URL in content. Returns the updated content,
+ * the number of conversions, the internal URLs that matched no published page,
+ * the internal URLs that carry a query string (which an xref cannot express),
+ * and the internal URLs left alone because no link text could be resolved for
+ * their fragment.
+ */
+function convertContent (content, resolverContext) {
+  const { hostnames, ignore = [] } = resolverContext
+  let result = ''
+  let cursor = 0
+  let converted = 0
+  const unmapped = []
+  const withQueryString = []
+  const withoutLinkText = []
+  for (const match of scanContentUrls(content)) {
+    let url
+    try {
+      url = new URL(match.url)
+    } catch {
+      continue
+    }
+    if (!hostnames.has(url.hostname) || match.inAttributeEntry || match.inAttributeValue) 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
+    // ?platform=kubernetes to preselect a tab. Leave the raw URL, which still
+    // works, rather than converting it lossily.
+    if (url.search) {
+      withQueryString.push(match.url)
+      continue
+    }
+    const entry = resolveUrlPath(url.pathname, resolverContext)
+    if (!entry) {
+      unmapped.push(match.url)
+      continue
+    }
+    const label = linkTextFor(match.label, url.hash, entry.page, resolverContext.resolveInclude)
+    if (label === undefined) {
+      withoutLinkText.push(match.url)
+      continue
+    }
+    result += content.slice(cursor, match.start) + entryToXref(entry, url.hash, label)
+    cursor = match.end
+    converted++
+  }
+  result += content.slice(cursor)
+  return { content: result, converted, unmapped, withQueryString, withoutLinkText }
+}
+
+module.exports.buildUrlMap = buildUrlMap
+module.exports.convertContent = convertContent
+module.exports.normalizeUrlPath = normalizeUrlPath

package/extensions/util/scan-content-urls.js

@@ -0,0 +1,121 @@
+'use strict'
+
+/**
+ * Scans AsciiDoc content for http(s) URLs that appear in prose, skipping
+ * URLs inside code contexts where rewriting or checking them would be wrong:
+ *
+ * - delimited listing (----), literal (....), fenced (```), and passthrough
+ *   (++++) blocks
+ * - inline code spans (`...`)
+ *
+ * Each match records enough position information for a caller to splice a
+ * replacement into the original content.
+ *
+ * Match shape:
+ * - url: the URL with any trailing sentence punctuation trimmed
+ * - label: text of a directly attached AsciiDoc link label ([...]), or null.
+ *   A label may span line breaks, which is common in generated content where
+ *   long lines are wrapped; its newlines are collapsed to single spaces
+ * - start/end: absolute offsets in content covering the whole replaceable
+ *   span (including a leading link: macro prefix and the label, if present)
+ * - hasLinkPrefix: true when the URL was written as link:https://...[...]
+ * - inAttributeEntry: true when the URL appears in an attribute entry line
+ *   (for example ":url-docs: https://..."), where a caller may want to leave
+ *   the value untouched
+ * - inAttributeValue: true when the URL is a macro attribute value (for
+ *   example image:d.png[alt,link=https://...]); rewriting one of these to an
+ *   xref macro would corrupt the surrounding macro, but the URL is still a
+ *   real link target worth checking
+ */
+
+const URL_RX = /(link:)?(https?:\/\/[^\s\][)"'<>]+)(\[[^\]]*\])?/g
+// Sentence punctuation, and the AsciiDoc formatting markup that closes around a
+// URL written as *emphasis* or **bold** (`**https://example.com/page**`), which
+// is not part of the URL.
+const TRAILING_PUNCT_RX = /[.,;:!?*_]+$/
+const ATTRIBUTE_ENTRY_RX = /^:!?[a-zA-Z0-9_][a-zA-Z0-9_-]*!?:(?:\s|$)/
+// Cap on how far a wrapped label may run, so an unmatched bracket somewhere in
+// prose cannot swallow the rest of the document.
+const MAX_WRAPPED_LABEL_LENGTH = 500
+
+function blockDelimiter (line) {
+  if (/^-{4,}$/.test(line)) return '-'
+  if (/^\.{4,}$/.test(line)) return '.'
+  if (/^`{3,}$/.test(line)) return '`'
+  if (/^\+{4,}$/.test(line)) return '+'
+  return null
+}
+
+function scanContentUrls (content) {
+  const matches = []
+  const lines = content.split('\n')
+  let offset = 0
+  let openDelimiter = null
+  for (const rawLine of lines) {
+    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
+    const delimiter = blockDelimiter(line)
+    if (delimiter) {
+      if (openDelimiter === delimiter) openDelimiter = null
+      else if (!openDelimiter) openDelimiter = delimiter
+    } else if (!openDelimiter) {
+      scanLine(line, offset, matches, content)
+    }
+    offset += rawLine.length + 1
+  }
+  return matches
+}
+
+/**
+ * Reads a link label that opens on this line but closes on a later one, which
+ * happens whenever a generator wraps long lines. Returns the label text with
+ * its line breaks collapsed, plus the offset just past the closing bracket.
+ * A blank line ends the search: that is a paragraph break, so the bracket
+ * belongs to something else.
+ */
+function readWrappedLabel (content, openIndex) {
+  if (content[openIndex] !== '[') return
+  const limit = Math.min(content.length, openIndex + MAX_WRAPPED_LABEL_LENGTH)
+  const closeIndex = content.indexOf(']', openIndex + 1)
+  if (closeIndex === -1 || closeIndex > limit) return
+  const raw = content.slice(openIndex + 1, closeIndex)
+  if (/\n[ \t]*\n/.test(raw)) return
+  return { label: raw.replace(/\s*\n\s*/g, ' '), end: closeIndex + 1 }
+}
+
+function scanLine (line, offset, matches, content) {
+  const inAttributeEntry = ATTRIBUTE_ENTRY_RX.test(line)
+  for (const match of line.matchAll(URL_RX)) {
+    const [, linkPrefix, rawUrl, rawLabel] = match
+    const backticksBefore = (line.slice(0, match.index).match(/`/g) || []).length
+    if (backticksBefore % 2 === 1) continue
+    const prefixLength = linkPrefix ? linkPrefix.length : 0
+    const start = offset + match.index
+    let url = rawUrl
+    let label = rawLabel ? rawLabel.slice(1, -1) : null
+    let end = start + prefixLength + url.length + (rawLabel ? rawLabel.length : 0)
+    if (!rawLabel) {
+      const wrapped = readWrappedLabel(content, start + prefixLength + url.length)
+      if (wrapped) {
+        label = wrapped.label
+        end = wrapped.end
+      } else {
+        url = url.replace(TRAILING_PUNCT_RX, '')
+        end = start + prefixLength + url.length
+      }
+    }
+    // A URL directly after an attribute assignment (link=, window=, ...) is a
+    // macro attribute value, not a standalone link.
+    const before = line.slice(0, match.index)
+    matches.push({
+      url,
+      label,
+      start,
+      end,
+      hasLinkPrefix: Boolean(linkPrefix),
+      inAttributeEntry,
+      inAttributeValue: /[\w-]=["']?$/.test(before),
+    })
+  }
+}
+
+module.exports = { scanContentUrls }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -24,6 +24,7 @@
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
     "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
     "test": "jest",
+    "test:e2e": "jest __tests__/e2e/",
     "test:mcp": "jest __tests__/mcp/",
     "test:mcp:integration": "jest __tests__/mcp/integration.test.js",
     "test:mcp:contract": "jest __tests__/mcp/cli-contract.test.js",
@@ -80,6 +81,8 @@
     "./extensions/resolve-xrefs-in-attachments": "./extensions/resolve-xrefs-in-attachments.js",
     "./extensions/unified-navigation": "./extensions/unified-navigation.js",
     "./extensions/conditional-home-redirect": "./extensions/conditional-home-redirect.js",
+    "./extensions/url-to-xref": "./extensions/url-to-xref.js",
+    "./extensions/external-link-checker": "./extensions/external-link-checker.js",
     "./macros/glossary": "./macros/glossary.js",
     "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",
@@ -101,6 +104,9 @@
     "mcp"
   ],
   "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/redpanda-data/docs-extensions-and-macros"

package/tools/rpk-docs/validate-output.js

@@ -23,12 +23,13 @@ const VALIDATION_RULES = [
       let match
       while ((match = urlPattern.exec(content)) !== null) {
         const url = match[1]
-        // Check if it's a docs.redpanda.com URL (should always be xref)
+        // docs.redpanda.com URLs are converted to xrefs at site build time
+        // by the url-to-xref Antora extension, so a raw one is informational
         if (url.includes('docs.redpanda.com')) {
           issues.push({
             line: getLineNumber(content, match.index),
-            message: `Raw docs.redpanda.com URL should be an xref: ${url}`,
-            severity: 'error'
+            message: `Raw docs.redpanda.com URL (converted to an xref by the url-to-xref extension at build time): ${url}`,
+            severity: 'info'
           })
         }
       }

package/cli-utils/convert-doc-links.js

@@ -1,58 +0,0 @@
-const { URL } = require('url');
-
-/**
- * Converts a docs.redpanda.com URL, optionally suffixed with a label in brackets, into an Antora xref resource ID string.
- *
- * If the input includes a label in square brackets (for example, `[Label]`), the label is preserved and appended to the resulting xref.
- *
- * @param {string} input - A docs.redpanda.com URL, optionally followed by a label in square brackets.
- * @returns {string} The corresponding Antora xref resource ID, with the label preserved if present.
- *
- * @throws {Error} If the input is not a valid URL or does not belong to docs.redpanda.com.
- */
-function urlToXref(input) {
-  // Peel off an optional “[label]”
-  let urlPart  = input;
-  let label    = '';
-  const mLabel = input.match(/^(.*)\[([^\]]+)\]$/);
-  if (mLabel) {
-    urlPart = mLabel[1];
-    label   = mLabel[2];
-  }
-
-  //Parse & validate
-  let url;
-  try {
-    url = new URL(urlPart);
-  } catch {
-    throw new Error(`Invalid URL: ${input}`);
-  }
-  if (!/docs\.redpanda\.com$/.test(url.hostname)) {
-    throw new Error(`Not a docs.redpanda.com URL: ${input}`);
-  }
-
-  // Strip any leading “/docs”, “/docs/vX.Y”, “/docs/current”, “/vX.Y” or “/current”
-  let p = url.pathname.replace(
-    /^\/(?:docs(?:\/(?:v?\d+\.\d+|current))?|v?\d+\.\d+|current)\/?/,
-    ''
-  );
-  // Drop trailing slash
-  p = p.replace(/\/$/, '');
-  const segments = p.split('/').filter(Boolean);
-
-  // Build module + path + .adoc
-  let xref;
-  if (segments.length === 0) {
-    xref = 'xref:index.adoc';
-  } else {
-    const moduleName = segments.shift();
-    const pagePath   = segments.join('/');
-    const fileName   = (pagePath || moduleName) + '.adoc';
-    xref = `xref:${moduleName}:${fileName}`;
-  }
-
-  // Re-attach label if there was one
-  return label ? `${xref}[${label}]` : xref;
-}
-
-module.exports = { urlToXref };