@redpanda-data/docs-extensions-and-macros 5.54.0 → 5.56.0

package/cli-utils/docs-links-to-xrefs.js

@@ -0,0 +1,174 @@
+'use strict'
+
+/**
+ * Converts docs.redpanda.com URLs in a generated page into xrefs before the
+ * page is committed to a docs repository.
+ *
+ * Reference pages generated from engineering sources (the CRD reference from
+ * Go doc comments, for example) arrive with absolute docs URLs, because a Go
+ * comment cannot carry an AsciiDoc xref. The url-to-xref Antora extension
+ * rewrites those at site build time, but the committed source then flips
+ * between xrefs and URLs on every regeneration, which buries the real content
+ * changes in a review diff. Converting here keeps the committed page stable.
+ *
+ * The URL-to-resource mapping is the one the extension uses: this module
+ * builds a real Antora content catalog from the docs checkout (aggregator plus
+ * classifier, worktree files, HEAD only) and hands it to the extension's
+ * buildUrlMap and convertContent. Nothing about the URL structure is guessed:
+ * a URL is converted only when it matches a page the checkout publishes,
+ * directly or through a page alias, and its fragment, if any, matches an
+ * anchor on that page; everything else is left as written and reported to the
+ * caller.
+ *
+ * Targets in the checkout's own component are written as module:page xrefs,
+ * the form the docs repos use by hand for same-component links. Pages of other
+ * components (Connect, Cloud) are not in a single-repo catalog, so URLs that
+ * point at them stay raw and are listed in the run output; the build-time
+ * extension still converts them on the site.
+ */
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const yaml = require('js-yaml')
+
+const { buildUrlMap, convertContent } = require('../extensions/url-to-xref')
+
+const DEFAULT_HOSTNAMES = ['docs.redpanda.com']
+// Mirrors the extension's default ignore list: docs-domain paths that Antora
+// does not publish (the Bump.sh API reference and the MCP endpoint).
+const DEFAULT_IGNORE = ['^/api/', '^/mcp(/|$)']
+const LATEST_VERSION_SEGMENT = 'current'
+
+/**
+ * Loads an Antora package, preferring the copy installed in the docs checkout
+ * (the site's own Antora version) over the one this package ships for its own
+ * preview build. The aggregator and classifier are dependencies of
+ * @antora/site-generator, so they are resolved through it.
+ */
+function requireAntora (name, searchPaths) {
+  const errors = []
+  for (const searchPath of searchPaths) {
+    try {
+      const siteGenerator = path.dirname(require.resolve('@antora/site-generator/package.json', { paths: [searchPath] }))
+      return require(require.resolve(name, { paths: [siteGenerator, searchPath] }))
+    } catch (err) {
+      errors.push(`${searchPath}: ${err.message.split('\n')[0]}`)
+    }
+  }
+  throw new Error(`Cannot load ${name}; install Antora in the docs repository (npm install) so generated links can be converted.\n${errors.join('\n')}`)
+}
+
+/**
+ * Reads the component name a docs checkout declares in antora.yml. A checkout
+ * without one is not an Antora component and cannot be mapped.
+ */
+function readComponentName (docsRoot) {
+  const descriptor = path.join(docsRoot, 'antora.yml')
+  if (!fs.existsSync(descriptor)) {
+    throw new Error(`No antora.yml in ${docsRoot}; a docs checkout is needed to map docs URLs to pages`)
+  }
+  const { name } = yaml.load(fs.readFileSync(descriptor, 'utf8')) || {}
+  if (!name) throw new Error(`${descriptor} declares no component name`)
+  return name
+}
+
+/**
+ * Builds the resolver context for a docs checkout: the extension's URL map,
+ * computed from an Antora content catalog of the checkout's worktree.
+ *
+ * @param {string} docsRoot - Root of a docs repository checkout (holds antora.yml).
+ * @param {Object} [options]
+ * @param {string[]} [options.hostnames] - Docs hostnames to convert.
+ * @param {string[]} [options.ignore] - URL path patterns to leave alone silently.
+ * @param {string} [options.cacheDir] - Antora cache directory.
+ * @returns {Promise<Object>} A context for convertContent, plus `component`
+ *   (the checkout's component name) and `pageCount`.
+ */
+async function buildDocsResolverContext (docsRoot, options = {}) {
+  const root = path.resolve(docsRoot)
+  const component = readComponentName(root)
+  const searchPaths = [root, path.join(__dirname, '..')]
+  const aggregateContent = requireAntora('@antora/content-aggregator', searchPaths)
+  const classifyContent = requireAntora('@antora/content-classifier', searchPaths)
+  const playbook = {
+    runtime: {
+      quiet: true,
+      fetch: false,
+      cacheDir: options.cacheDir || fs.mkdtempSync(path.join(os.tmpdir(), 'docs-links-antora-cache-')),
+      log: { level: 'silent' },
+    },
+    site: {},
+    // The published shape of the live site; normalizeUrlPath in the extension
+    // makes the extension style irrelevant to matching, and candidatePaths
+    // covers both the symbolic and the real version segment.
+    urls: { htmlExtensionStyle: 'indexify', latestVersionSegment: LATEST_VERSION_SEGMENT },
+    // HEAD of the local checkout, read from the worktree, so an unpushed
+    // branch and uncommitted pages count as published.
+    content: { sources: [{ url: root, branches: 'HEAD' }] },
+  }
+  const contentCatalog = classifyContent(playbook, await aggregateContent(playbook))
+  const pageCount = contentCatalog.getPages((page) => page.out).length
+  return Object.assign(buildUrlMap(contentCatalog), {
+    hostnames: new Set(options.hostnames || DEFAULT_HOSTNAMES),
+    ignore: (options.ignore || DEFAULT_IGNORE).map((pattern) => new RegExp(pattern)),
+    latestVersionSegment: LATEST_VERSION_SEGMENT,
+    localComponent: component,
+    resolveInclude: (spec, page) => contentCatalog.resolveResource(spec, page.src, 'partial', ['partial', 'page']),
+    component,
+    pageCount,
+  })
+}
+
+/**
+ * Converts the docs URLs in a string. Thin wrapper over the extension's
+ * convertContent so callers do not depend on the extension module directly.
+ */
+function convertDocsLinks (content, context) {
+  return convertContent(content, context)
+}
+
+/**
+ * Converts the docs URLs in a file in place. The file is rewritten only when
+ * something changed.
+ *
+ * @returns {Object} `{ converted, unmapped, withQueryString, withoutLinkText, missingAnchor }`
+ *   with the raw URLs in each list deduplicated.
+ */
+function convertDocsLinksInFile (filePath, context) {
+  const before = fs.readFileSync(filePath, 'utf8')
+  const result = convertDocsLinks(before, context)
+  if (result.converted) fs.writeFileSync(filePath, result.content, 'utf8')
+  return {
+    converted: result.converted,
+    unmapped: [...new Set(result.unmapped)],
+    withQueryString: [...new Set(result.withQueryString)],
+    withoutLinkText: [...new Set(result.withoutLinkText)],
+    missingAnchor: [...new Set(result.missingAnchor)],
+  }
+}
+
+/**
+ * Formats the outcome of a file conversion for the run output: one summary
+ * line, then every URL that was left as written and why.
+ */
+function formatDocsLinkReport (result, filePath) {
+  const lines = [`Converted ${result.converted} docs URL${result.converted === 1 ? '' : 's'} to xrefs in ${filePath}`]
+  const leftRaw = (urls, reason) => {
+    if (!urls.length) return
+    lines.push(`Left ${urls.length} docs URL${urls.length === 1 ? '' : 's'} as written (${reason}):`)
+    for (const url of urls) lines.push(`  ${url}`)
+  }
+  leftRaw(result.unmapped, 'no page in this checkout matches; the url-to-xref extension converts cross-component URLs at build time and warns about broken ones')
+  leftRaw(result.withQueryString, 'an xref cannot carry a query string')
+  leftRaw(result.withoutLinkText, 'the target page could not be read to check the fragment')
+  leftRaw(result.missingAnchor || [], 'anchor not found: the page exists but has no section or anchor with that id')
+  return lines.join('\n')
+}
+
+module.exports = {
+  buildDocsResolverContext,
+  convertDocsLinks,
+  convertDocsLinksInFile,
+  formatDocsLinkReport,
+}

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

@@ -9,9 +9,10 @@
  */
 function formatHelmSpec (doc) {
   const formatted = doc
-    // pandoc escapes footnote-style references inconsistently
-    .replace(/(\[\d+\])\]\./g, '$1\\].')
-    .replace(/(\[\d+\])\]\]/g, '$1\\]\\]')
+    // an array index inside a heading's link text (ingress.hosts[0].host)
+    // closes the link text early unless its "]" is escaped
+    .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')

package/cli-utils/generated-marker.js

@@ -0,0 +1,43 @@
+'use strict'
+
+// The one comment line every doc-tools generator writes at the top of each
+// file it produces. convert-to-markdown reads it and reports the provenance
+// in the Markdown twins (page-generated-content, page-generated-by,
+// page-generated-from, page-generated-sources), so a reader or an agent can
+// tell generated text from hand-written text and knows where a fix goes.
+//
+// The first two sentences are the legacy banner that existing tests and the
+// guard-generated-files check already look for, so they never change.
+//
+// The marker names no doc-tools version. Generated files are committed, so a
+// version in the marker would rewrite the first line of every generated file
+// on every release even when nothing else changed, and every auto-docs PR
+// would carry hundreds of one-line diffs. DOC_TOOLS_VERSION is for provenance
+// recorded at build time (pages generated during the site build), where no
+// file is committed.
+const pkg = require('../package.json')
+
+const GENERATED_MARKER_LEGACY = 'This content is autogenerated. Do not edit manually.'
+const DOC_TOOLS_VERSION = pkg.version
+
+/**
+ * Build the marker line, without a trailing newline.
+ * @param {string} generator - Short generator name, for example `property-docs`
+ * @param {string} source - Where the text comes from, as a noun phrase, for
+ *   example `the configuration property definitions in redpanda-data/streaming-enterprise`
+ * @param {string} [hint] - How to change the text, as one or more sentences
+ * @returns {string} `// This content is autogenerated. ... Generated by doc-tools (<generator>) from <source>. <hint>`
+ */
+function generatedMarker (generator, source, hint) {
+  if (!generator || !source) throw new Error('generatedMarker needs a generator and a source')
+  const parts = [
+    GENERATED_MARKER_LEGACY,
+    `Generated by doc-tools (${generator}) from ${source.replace(/\.$/, '')}.`,
+  ]
+  // Handlebars passes its options object as the last argument when a
+  // template omits the hint, so only a string counts as one.
+  if (typeof hint === 'string' && hint.trim()) parts.push(hint.trim())
+  return `// ${parts.join(' ')}`
+}
+
+module.exports = { generatedMarker, GENERATED_MARKER_LEGACY, DOC_TOOLS_VERSION }

package/cli-utils/helm-commented-values.js

@@ -24,6 +24,19 @@
  *
  *    yields `external.domain`.
  *
+ *    The description attaches to the first commented-out key after it. When
+ *    more commented-out siblings follow in the same comment run, each one
+ *    with its own plain comment above it is documented by that comment:
+ *
+ *      external:
+ *        # -- Optional domain advertised to external clients.
+ *        # domain: local
+ *        # Optional list of advertised addresses.
+ *        # addresses:
+ *
+ *    yields `external.domain` and `external.addresses`. A sibling with no
+ *    comment of its own is not documented.
+ *
  * 2. Explicit, fully-qualified syntax that works anywhere in the file:
  *
  *      # @doc external.addresses -- Optional list of advertised addresses.
@@ -33,6 +46,8 @@
  * displayed default, which is otherwise `nil`.
  */
 
+const { spawnSync } = require('child_process')
+
 // Key names never contain dots or slashes: a dotted or slashed "key" in a
 // comment is prose or a URL (`# docker.redpanda.com/...:4.101.0`), and
 // treating it as a key both fabricates a path and truncates the description.
@@ -89,10 +104,26 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
   const records = []
   const stack = [] // enclosing real keys: { name, indent }
 
-  // Accumulating comment block: { descLines, default, candidate }. The
-  // candidate is the key the block documents; emission is deferred to the
-  // end of the block so that a later key line at the same depth supersedes a
-  // prose line that merely looks like a key (`# example:`, `# default: 30s`).
+  // Accumulating comment block: { marked, descLines, default, candidate }.
+  // A marked block opens at a `# --` line. Its description is every comment
+  // line up to the first commented-out key, and that key (the candidate) is
+  // the one it documents, the same way helm-docs reads a `# --` block as the
+  // description of the key directly below it.
+  //
+  // Optional values often ship as a run of commented-out siblings under one
+  // marker, each with its own plain comment above it:
+  //
+  //     # -- Optional domain.
+  //     # domain: local
+  //     # Optional list of addresses.
+  //     # addresses:
+  //
+  // Once a block has its key, a plain comment line at that key's depth (or
+  // shallower) ends it and opens an unmarked block for the next sibling, so
+  // `addresses` is documented by its own comment instead of handing its key
+  // line to the domain description. An unmarked block is only ever emitted
+  // when it has description text and a key; it never becomes a dead marker.
+  // The run ends at the first non-comment line, as a marked block does.
   let block = null
   let atDoc = null // accumulating @doc entry: { path, descLines, default }
   let skipScalarIndent = -1 // inside a block scalar when >= 0
@@ -135,6 +166,7 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
   // The generator drops these; the linter reports them, because their
   // description silently never ships.
   const emitDead = (b) => {
+    if (!b.marked) return
     record({
       kind: 'dead-marker',
       descLines: b.descLines,
@@ -145,12 +177,26 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
     })
   }
 
+  const openUnmarkedBlock = (line, firstDescLine) => ({
+    marked: false,
+    markerLine: line,
+    lastLine: line,
+    descLines: firstDescLine === null ? [] : [firstDescLine],
+    default: '',
+    annotations: {},
+    candidate: null,
+  })
+
   // Emit the active block's candidate, if any, and close the block. The
   // emitted key suppresses its own commented subtree until real content
   // appears, so nested example structures do not emit bogus paths.
   const flushBlock = () => {
     if (!block) return
-    if (block.candidate) {
+    if (block.candidate && !block.marked && !block.descLines.some((l) => l.trim() !== '')) {
+      // An unmarked sibling with no comment of its own has nothing to say;
+      // still suppress its commented subtree.
+      suppressInnerIndent = block.candidate.effIndent
+    } else if (block.candidate) {
       const { name, effIndent } = block.candidate
       const parents = stack.filter((k) => k.indent < effIndent).map((k) => k.name)
       record({
@@ -233,13 +279,26 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
       // "key" is a URL scheme and the "value" is the scheme-relative part.
       const simpleValue = (value === '' || !/\s/.test(value)) && !value.startsWith('/')
       if (block && simpleValue) {
-        if (!block.candidate || effIndent <= block.candidate.effIndent) {
-          // The last key-shaped line at the block's shallowest depth wins:
-          // an earlier line at the same depth was prose shaped like a key,
-          // and deeper lines are nested example structures.
-          block.candidate = { name: commentedKey[3], effIndent }
+        const key = { name: commentedKey[3], effIndent }
+        if (!block.candidate || effIndent < block.candidate.effIndent) {
+          // The first key line after the description is the documented key.
+          // A shallower key replaces it, because the deeper line was a nested
+          // example structure rather than the key itself.
+          block.candidate = key
+          block.lastLine = i
+        } else if (effIndent > block.candidate.effIndent) {
+          // A nested line of the documented key's commented-out example.
+          block.lastLine = i
+        } else {
+          // A sibling key with no comment of its own. The documented key is
+          // complete; the sibling opens an unmarked block, which flushBlock
+          // drops because it has no description, while still suppressing
+          // the sibling's own commented subtree.
+          flushBlock()
+          suppressInnerIndent = -1
+          block = openUnmarkedBlock(i, null)
+          block.candidate = key
         }
-        block.lastLine = i
         continue
       }
     }
@@ -248,18 +307,30 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
     if (descMarker) {
       flushAtDoc()
       flushBlock()
-      block = { markerLine: i, lastLine: i, descLines: [descMarker[1]], default: '', annotations: {}, candidate: null }
+      block = { marked: true, markerLine: i, lastLine: i, descLines: [descMarker[1]], default: '', annotations: {}, candidate: null }
       continue
     }
 
     const comment = line.match(COMMENT_RE)
     if (comment && line.trim().startsWith('#')) {
       if (atDoc) { atDoc.descLines.push(comment[1]); atDoc.lastLine = i }
-      // Description lines precede the documented key; once a candidate
-      // exists, trailing comment lines belong to its example structure and
-      // only extend the span.
+      // Description lines precede the documented key.
       else if (block && !block.candidate) { block.descLines.push(comment[1]); block.lastLine = i }
-      else if (block) block.lastLine = i
+      else if (block) {
+        // After the key: deeper lines, list items, and bare `#` lines belong
+        // to its commented-out example. Prose at the key's own depth or
+        // shallower is the description of the next commented-out sibling.
+        const [, before, after] = line.match(/^(\s*)#(\s*)/)
+        const proseIndent = before.length + Math.max(0, after.length - 1)
+        const text = comment[1].trim()
+        if (text === '' || text.startsWith('- ') || text === '-' || proseIndent > block.candidate.effIndent) {
+          block.lastLine = i
+        } else {
+          flushBlock()
+          suppressInnerIndent = -1
+          block = openUnmarkedBlock(i, comment[1])
+        }
+      }
       continue
     }
 
@@ -270,8 +341,9 @@ function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
     flushAtDoc()
 
     const realKey = line.match(REAL_KEY_RE)
-    if (attachRealKeys && realKey && block && !block.candidate && block.lastLine === i - 1) {
-      // helm-docs' own attachment: the block sits DIRECTLY above a real key.
+    if (attachRealKeys && realKey && block && block.marked && !block.candidate && block.lastLine === i - 1) {
+      // helm-docs' own attachment: the marked block sits DIRECTLY above a
+      // real key.
       const indent = realKey[1].length
       while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop()
       const name = realKey[2].replace(/^"|"$/g, '')
@@ -394,6 +466,31 @@ function filterEntriesBySchema (entries, schema) {
   return { accepted, rejected }
 }
 
+/**
+ * Convert Markdown to AsciiDoc with pandoc. `generate helm-spec` uses this for
+ * the helm-docs README and for each values.yaml comment it injects, so both
+ * get the same conversion. values.yaml comments are Markdown (helm-docs copies
+ * them into the README as is), so without it an injected comment's links and
+ * emphasis are published as literal Markdown.
+ *
+ * The `smart` extension is turned off on input. With it, pandoc turns straight
+ * quotes into curly ones and writes them as ``text'', which only AsciiDoc
+ * Python understood. Asciidoctor prints those backticks and apostrophes
+ * literally, so straight quotes are passed through instead.
+ *
+ * @param {string} markdown - Markdown text.
+ * @returns {string} AsciiDoc text, without a trailing newline.
+ * @throws {Error} When pandoc cannot be run or exits non-zero.
+ */
+function markdownToAsciiDoc (markdown) {
+  if (!markdown || !markdown.trim()) return markdown
+  const r = spawnSync('pandoc', ['-f', 'markdown-smart', '-t', 'asciidoc'], { input: markdown, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  if (r.error) throw new Error(`pandoc failed: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`pandoc exited ${r.status}: ${(r.stderr || '').trim()}`)
+  if (r.stderr) process.stderr.write(r.stderr)
+  return r.stdout.replace(/\s+$/, '')
+}
+
 // Neutralize description lines that would otherwise parse as AsciiDoc
 // structure when injected at block level: section titles re-parent the
 // following sections, and an unclosed block delimiter swallows the rest of
@@ -414,11 +511,17 @@ function sanitizeDescription (text) {
  * sections and are inserted in alphabetical key order. Keys that are already
  * documented are skipped.
  *
+ * Descriptions and defaults come from values.yaml comments, which are
+ * Markdown. Pass `toAsciiDoc` (for example `markdownToAsciiDoc`) to convert
+ * them the way the rest of the document was converted. Without it, the text
+ * is inserted as is.
+ *
  * @param {string} adoc - The converted AsciiDoc document.
  * @param {Array<{path: string, description: string, default: string}>} entries
+ * @param {{toAsciiDoc?: (markdown: string) => string}} [options]
  * @returns {{doc: string, injected: string[], sectionsFound: number}}
  */
-function injectIntoAsciiDoc (adoc, entries) {
+function injectIntoAsciiDoc (adoc, entries, { toAsciiDoc = (text) => text } = {}) {
   // The label may itself contain brackets (`[storage.volume[0].name]` in the
   // connectors chart), so it is matched to end of line rather than to the
   // first closing bracket.
@@ -460,9 +563,9 @@ function injectIntoAsciiDoc (adoc, entries) {
     const section = [
       `=== link:++${urlPrefix}${entry.path}++[${entry.path}]`,
       '',
-      sanitizeDescription(entry.description),
+      sanitizeDescription(toAsciiDoc(entry.description)),
       '',
-      `*Default:* ${entry.default}`,
+      `*Default:* ${toAsciiDoc(entry.default)}`,
       '',
       '',
     ].join('\n')
@@ -492,6 +595,7 @@ module.exports = {
   parseValuesFile,
   extractCommentedValueDocs,
   injectIntoAsciiDoc,
+  markdownToAsciiDoc,
   filterEntriesBySchema,
   isPathAllowedBySchema,
   // Exported so the lint surface cannot hold its own copy. Every one of these

package/cli-utils/self-managed-docs-branch.js

@@ -43,51 +43,57 @@ async function fetchRemoteAntoraVersion(deps = {}) {
 }
 
 /**
- * Determines the appropriate documentation branch for a given operator tag based on the remote Antora version.
+ * Reports whether a branch exists in the docs repository.
  *
- * Normalizes the input tag, extracts the major.minor version, and applies version-specific logic to select the correct branch. Verifies that the chosen branch exists in the remote repository.
+ * @param {string} branch - Branch name, such as "main" or "v/25.1".
+ * @returns {boolean} True when `git ls-remote` finds the branch.
+ */
+function docsBranchExists(branch) {
+  const repo = 'https://github.com/redpanda-data/docs.git'
+  return spawnSync('git', ['ls-remote', '--exit-code', '--heads', repo, `refs/heads/${branch}`], {
+    stdio: 'ignore'
+  }).status === 0
+}
+
+/**
+ * Determines the appropriate documentation branch for a given operator tag or branch based on the remote Antora version.
+ *
+ * Normalizes the input, extracts the major.minor version, and applies version-specific logic to select the correct branch. Verifies that the chosen branch exists in the remote repository.
+ * A ref with no version, such as `main`, `dev`, or a feature branch, holds content for the next release, which the docs repository keeps on `main`.
  *
- * @param {string} operatorTag - The operator tag to evaluate (for example, "operator/v25.1.2" or "v25.1.2").
+ * @param {string} operatorRef - The operator tag or branch to evaluate (for example, "operator/v25.1.2", "v25.1.2", "release/v25.1.x", or "main").
+ * @param {object} [deps] - Injectable for tests: { antoraVersion, branchExists, fetchImpl, token }.
  * @returns {Promise<string>} The name of the documentation branch to use.
  *
- * @throws {Error} If the tag cannot be parsed or if the determined branch does not exist in the remote repository.
+ * @throws {Error} If the Antora version cannot be fetched or if the determined branch does not exist in the remote repository.
  */
-async function determineDocsBranch(operatorTag) {
-  // Strip any "operator/" prefix
-  const TAG = operatorTag.replace(/^(?:operator|release)\//, '')
-  // Pull in the remote Antora version
-  const ANTORA = await fetchRemoteAntoraVersion()
+async function determineDocsBranch(operatorRef, deps = {}) {
+  const branchExists = deps.branchExists || docsBranchExists
+  // Strip any "operator/" or "release/" prefix
+  const TAG = operatorRef.replace(/^(?:operator|release)\//, '')
   // Extract v<major>.<minor>
   const mm = TAG.match(/^v(\d+\.\d+)/)
   const filtered = mm ? `v${mm[1]}` : null
 
-  if (!filtered) {
-    throw new Error(`Could not parse major.minor from ${TAG}`)
-  }
-  // We started versioning the operator in line with Redpanda core versions. But when v2.4.x was the latest version, the docs were still on 25.1 and v25.1.x of the operator was still in beta. So we need to handle this special case.
   let branch
-  if (filtered === 'v2.4') {
-    if (ANTORA === '25.1') {
+  if (!filtered) {
+    branch = 'main'
+  } else {
+    // Pull in the remote Antora version
+    const ANTORA = deps.antoraVersion || await fetchRemoteAntoraVersion(deps)
+    // We started versioning the operator in line with Redpanda core versions. But when v2.4.x was the latest version, the docs were still on 25.1 and v25.1.x of the operator was still in beta. So we need to handle this special case.
+    if (filtered === 'v2.4') {
+      branch = ANTORA === '25.1' ? 'main' : 'v/24.3'
+    // For all other versions use the v<major>.<minor> branch unless it is the current version, in which case we use 'main'.
+    } else if (filtered === `v${ANTORA}`) {
       branch = 'main'
     } else {
-      branch = 'v/24.3'
+      branch = `v/${filtered.slice(1)}`
     }
-  // For all other versions use the v<major>.<minor> branch unless it is the current version, in which case we use 'main'.
-  } else if (filtered === `v${ANTORA}`) {
-    branch = 'main'
-  } else {
-    branch = `v/${filtered.slice(1)}`
   }
 
-  // Verify branch exists
-  const repo = 'https://github.com/redpanda-data/docs.git'
-  const ref  = `refs/heads/${branch}`
-  const ok = spawnSync('git', ['ls-remote', '--exit-code', '--heads', repo, ref], {
-    stdio: 'ignore'
-  }).status === 0
-
-  if (!ok) {
-    throw new Error(`Docs branch ${branch} not found in ${repo}`)
+  if (!branchExists(branch)) {
+    throw new Error(`Docs branch ${branch} not found in https://github.com/redpanda-data/docs.git`)
   }
 
   return branch

package/extension-utils/html-utils.js

@@ -0,0 +1,27 @@
+'use strict'
+
+/**
+ * Shared HTML utility functions for extensions and macros.
+ */
+
+/**
+ * Escape a value for safe inclusion in HTML text or inside a double-quoted
+ * attribute. Escaping `&` first is what keeps the result idempotent-safe for a
+ * single pass; escaping `"` is what stops an author-supplied string from ending
+ * the attribute it sits in.
+ *
+ * @param {*} value - Value to escape. `null` and `undefined` become ''.
+ * @returns {string} The escaped string.
+ */
+function escapeHtml (value) {
+  if (value === null || value === undefined) return ''
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+module.exports = {
+  escapeHtml,
+}

package/extension-utils/llms-utils.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { decode } = require('html-entities');
+
 /**
  * Shared utilities for llms.txt generation and markdown processing.
  * Used by both convert-to-markdown.js and convert-llms-to-txt.js.
@@ -115,9 +117,11 @@ const MAX_INDEX_CHARS = 45000;
  */
 const MAX_INDEX_DESCRIPTION_CHARS = 200;
 
+// Titles and descriptions arrive as converted HTML, so tags are stripped and
+// entities decoded. Decoding comes after stripping: an escaped placeholder
+// such as `&lt;name&gt;` must survive as `<name>`, not be removed as a tag.
 function oneLine(text) {
-  return String(text || '')
-    .replace(/<[^>]+>/g, '')
+  return decode(String(text || '').replace(/<[^>]+>/g, ''))
     .replace(/\s+/g, ' ')
     .trim();
 }