@redpanda-data/docs-extensions-and-macros 5.8.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')
 
 // --------------------------------------------------------------------
@@ -827,6 +826,48 @@ automation
     migrateMetadataToPartials({ write: Boolean(options.write) })
   })
 
+/**
+ * @description One-time migration of plain-backtick property mentions to the
+ * prop: inline macro, so property tooltips become opt-in. Only names that
+ * exist in the published property reference JSON AND contain a separator
+ * (_ or .) are converted. Separator-free names such as admin, brokers, rack,
+ * retries, and superusers are the ambiguous words that motivated opt-in
+ * marking, so they are always left for a human. Dry run unless --write is given.
+ *
+ * @example
+ * # Preview the conversion from a docs repo checkout
+ * npx doc-tools generate migrate-property-refs --properties modules/reference/attachments/redpanda-properties-v26.2.1.json
+ *
+ * # Apply it
+ * npx doc-tools generate migrate-property-refs --properties modules/reference/attachments/redpanda-properties-v26.2.1.json --write
+ */
+automation
+  .command('migrate-property-refs')
+  .description('One-time migration of `property_name` prose mentions to prop:property_name[] macros. Dry run unless --write is given.')
+  .requiredOption('--properties <path>', 'Path to the published redpanda-properties JSON to validate names against')
+  .option('--docs-dir <path>', 'Docs repo root containing modules/', '.')
+  .option('--config-refs', 'Also convert config_ref macro calls to prop macro calls')
+  .option('--write', 'Apply changes (default is a dry run that only reports)')
+  .action((options) => {
+    const { migrate } = require('../tools/migrate-property-refs.js')
+    const propertiesJson = JSON.parse(fs.readFileSync(path.resolve(options.properties), 'utf8'))
+    const result = migrate({
+      docsDir: path.resolve(options.docsDir),
+      propertiesJson,
+      write: Boolean(options.write),
+      configRefs: Boolean(options.configRefs),
+    })
+    result.changed
+      .sort((a, b) => b.count - a.count)
+      .forEach(({ file, count }) => console.log(`${String(count).padStart(4)}  ${file}`))
+    console.log(`\n${options.write ? 'Converted' : 'Would convert'} ${result.conversions} mention(s) across ${result.changed.length} of ${result.files} files.`)
+    console.log(`Left alone (ambiguous, no separator): ${result.ambiguous.join(', ')}`)
+    if (result.skippedConfigRefs && result.skippedConfigRefs.length) {
+      console.log(`config_ref calls left alone (names not in the published JSON): ${result.skippedConfigRefs.join(', ')}`)
+    }
+    if (!options.write && result.conversions) console.log('Re-run with --write to apply.')
+  })
+
 /**
  * generate property-docs
  *
@@ -1635,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}`)
     }
@@ -1947,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 })
@@ -2133,5 +2117,131 @@ automation
     }
   })
 
+const validation = new Command('validate').description('Validate docs data against internal sources of truth')
+
+/**
+ * @description Checks the enterprise features registry (the shared component's
+ * enterprise-features.yml in the docs repo) against the internal sources of
+ * truth: the license_required_feature enum and config::enterprise<> property
+ * wrappers in redpanda core, the enterprise plugins in connect info.csv, and
+ * the hand-maintained disable-enterprise-features.adoc table.
+ * Exit codes: 0 clean, 1 drift found (error or needs-human findings), 2 execution error.
+ *
+ * @why A feature must only be documented as enterprise under its approved
+ * external name. This check catches new license-gated features in core that
+ * have no registry entry yet, registry pointers that no longer match core,
+ * and stale connect enterprise lists.
+ *
+ * @example
+ * # Check everything against the default remote sources
+ * npx doc-tools validate enterprise-features
+ *
+ * # Check a local registry file (for example, in docs repo CI)
+ * npx doc-tools validate enterprise-features --registry shared/modules/ROOT/partials/enterprise-features.yml
+ *
+ * # Regenerate the rpk name-mapping partial
+ * npx doc-tools validate enterprise-features --write-mapping modules/get-started/partials/licensing/feature-name-mapping.adoc
+ *
+ * @requirements
+ * Network access to raw.githubusercontent.com for any source not supplied
+ * with a local path option.
+ */
+validation
+  .command('enterprise-features')
+  .description('Check the enterprise features registry against core, connect, and docs sources of truth')
+  .option('--registry <path>', 'Local path to enterprise-features.yml (default: fetch from docs repo main)')
+  .option('--tag <ref>', 'Redpanda git ref for the core headers', 'dev')
+  .option('--connect-ref <ref>', 'Connect git ref for info.csv', 'main')
+  .option('--docs-ref <ref>', 'Docs repo git ref for remote fetches', 'main')
+  .option('--disable-page <path>', 'Local path to disable-enterprise-features.adoc (default: fetch from docs repo)')
+  .option('--antora <path>', 'Local path to rp-connect-docs antora.yml (default: fetch from rp-connect-docs main)')
+  .option('--properties <path>', 'Local path to a generated cluster-properties JSON; enables existence checks for gating properties')
+  .option('--skip-connect', 'Skip the connect info.csv comparison')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .option('--write-mapping <path>', 'Write the internal-to-external name mapping partial to this path')
+  .action(async (options) => {
+    const { runChecks, buildMappingPartial } = require('../tools/enterprise-features/verify')
+    const { extractAntoraEnterpriseComponents } = require('../tools/enterprise-features/parsers')
+    const yamlLib = require('js-yaml')
+
+    const RAW = 'https://raw.githubusercontent.com'
+    // Sources that fail to load are reported as error-level findings rather
+    // than silently skipped, so CI cannot pass on a check that never ran.
+    const failedSources = []
+    async function fetchText (url, sourceName) {
+      const resp = await fetch(url)
+      if (!resp.ok) {
+        if (sourceName) {
+          failedSources.push({ level: 'error', check: 'fetch', message: `Could not load ${sourceName} (${url}): ${resp.status} ${resp.statusText}. The related checks did not run.` })
+          return undefined
+        }
+        throw new Error(`Failed to fetch ${url}: ${resp.status} ${resp.statusText}`)
+      }
+      return resp.text()
+    }
+    const readLocal = (p) => fs.readFileSync(path.resolve(p), 'utf8')
+
+    try {
+      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 infoCsv = options.skipConnect
+        ? undefined
+        : await fetchText(`${RAW}/redpanda-data/connect/${options.connectRef}/internal/plugins/info.csv`, 'connect info.csv')
+      const disablePage = options.disablePage
+        ? readLocal(options.disablePage)
+        : await fetchText(`${RAW}/redpanda-data/docs/${options.docsRef}/modules/get-started/pages/licensing/disable-enterprise-features.adoc`, 'disable-enterprise-features.adoc')
+      const antoraYaml = options.antora
+        ? readLocal(options.antora)
+        : await fetchText(`${RAW}/redpanda-data/rp-connect-docs/main/antora.yml`, 'rp-connect-docs antora.yml')
+      const antoraEnterpriseComponents = antoraYaml
+        ? extractAntoraEnterpriseComponents(yamlLib.load(antoraYaml))
+        : undefined
+
+      let allPropertyNames
+      if (options.properties) {
+        const propertyData = JSON.parse(readLocal(options.properties))
+        allPropertyNames = Object.keys(propertyData.properties || propertyData)
+      }
+
+      const { findings, features, enumValues } = runChecks({
+        registryYaml,
+        coreHeader,
+        configurationHeader,
+        infoCsv,
+        antoraEnterpriseComponents,
+        disablePage,
+        allPropertyNames,
+      })
+      findings.push(...failedSources)
+
+      if (options.writeMapping) {
+        const partial = buildMappingPartial(features, enumValues)
+        fs.mkdirSync(path.dirname(path.resolve(options.writeMapping)), { recursive: true })
+        fs.writeFileSync(path.resolve(options.writeMapping), `${partial}\n`)
+        console.log(`Wrote name mapping partial to ${options.writeMapping}`)
+      }
+
+      const drift = findings.filter((f) => f.level === 'error' || f.level === 'needs-human')
+      if (options.format === 'json') {
+        console.log(JSON.stringify({ findings, drift: drift.length > 0 }, null, 2))
+      } else {
+        for (const level of ['error', 'needs-human', 'info']) {
+          for (const f of findings.filter((entry) => entry.level === level)) {
+            console.log(`${level.toUpperCase()} [${f.check}] ${f.message}`)
+          }
+        }
+        console.log(drift.length ? `\n${drift.length} finding(s) need attention.` : '\nRegistry is in sync with all checked sources.')
+      }
+      process.exit(drift.length ? 1 : 0)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(2)
+    }
+  })
+
 programCli.addCommand(automation)
+programCli.addCommand(validation)
 programCli.parse(process.argv)

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/convert-to-markdown.js

@@ -187,6 +187,116 @@ function generateFrontmatter(page) {
   return `---\n${yamlContent}---\n\n`
 }
 
+// Default class the enterprise inline macro puts on its wrapping span. The
+// macro lets a playbook override it via the enterprise-feature-role document
+// attribute, so match on a substring rather than the exact value.
+const ENTERPRISE_FEATURE_CLASS = 'enterprise-feature'
+
+// Status words collected into the single trailing parenthetical.
+const ENTERPRISE_STATUS = 'enterprise'
+const BETA_STATUS = 'beta'
+
+// Class the badge macro puts on a beta badge.
+const BETA_BADGE_CLASS = 'badge--beta'
+
+// Explicit textual marker for enterprise features in Markdown output.
+const ENTERPRISE_MARKER = `(${ENTERPRISE_STATUS})`
+
+/**
+ * Format one parenthetical from the status words that apply to a feature.
+ *
+ * A beta enterprise feature carries two markers, and emitting them separately
+ * reads as "Stretch Clusters (enterprise) (beta)". One list avoids the stutter.
+ *
+ * @param {string[]} statuses - Status words, in display order.
+ * @returns {string} Parenthetical, or an empty string when there are none.
+ */
+function formatStatusMarker (statuses) {
+  const words = statuses.filter(Boolean)
+  return words.length ? `(${words.join(', ')})` : ''
+}
+
+function hasClass (node, className) {
+  if (!node || node.nodeName !== 'SPAN') return false
+  const classAttr = node.getAttribute?.('class') || node.className || ''
+  return typeof classAttr === 'string' && classAttr.includes(className)
+}
+
+/**
+ * The next sibling element, skipping the whitespace text nodes that sit between
+ * the enterprise span and a badge that follows it.
+ */
+function nextElementSibling (node) {
+  let sibling = node && node.nextSibling
+  while (sibling && sibling.nodeType === 3 && !(sibling.textContent || '').trim()) {
+    sibling = sibling.nextSibling
+  }
+  return sibling && sibling.nodeType === 1 ? sibling : null
+}
+
+/**
+ * Turndown rules that keep the enterprise and beta signals in Markdown output.
+ *
+ * In HTML both signals are carried by things Turndown discards. The enterprise
+ * badge is drawn by CSS from the span's class and explained by a title tooltip,
+ * so `enterprise:Tiered Storage[]` would arrive in Markdown as the bare words
+ * "Tiered Storage", indistinguishable from any other feature name. The beta
+ * badge does survive, because its label keeps real bracketed text, but it lands
+ * as a second parenthetical right after the first.
+ *
+ * These rules emit one trailing parenthetical instead, listing every status
+ * that applies, and pass the span's already-converted inner Markdown through
+ * untouched so a linked feature keeps its link:
+ *
+ *   [Stretch Clusters](../deploy/stretch-clusters.md) (enterprise, beta)
+ *
+ * The beta badge is a sibling of the enterprise span rather than a child. The
+ * enterprise rule looks ahead for it and, when it finds one, emits no marker of
+ * its own and hands the combined marker to the badge. Emitting it there rather
+ * than on the enterprise span reuses the whitespace already between the two
+ * elements, instead of suppressing the badge and leaving a doubled space.
+ *
+ * @returns {{enterpriseFeature: object, betaBadge: object}} Turndown rules,
+ *   both of which must be registered.
+ */
+function createEnterpriseFeatureRules () {
+  // Scoped per call so each converter tracks its own deferred markers.
+  const deferredToBadge = new WeakSet()
+
+  const enterpriseFeature = {
+    filter: (node) => hasClass(node, ENTERPRISE_FEATURE_CLASS),
+    replacement: (content, node) => {
+      const inner = (content || '').trim()
+      // An empty span carries no feature to mark.
+      if (!inner) return ''
+      // Nested or already-marked content must not collect a second marker.
+      if (inner.toLowerCase().endsWith(ENTERPRISE_MARKER)) return inner
+
+      const sibling = nextElementSibling(node)
+      if (hasClass(sibling, BETA_BADGE_CLASS)) {
+        // The badge renders "(enterprise, beta)" for both of us.
+        deferredToBadge.add(sibling)
+        return inner
+      }
+      return `${inner} ${ENTERPRISE_MARKER}`
+    },
+  }
+
+  const betaBadge = {
+    filter: (node) => hasClass(node, BETA_BADGE_CLASS),
+    replacement: (content, node) =>
+      deferredToBadge.has(node)
+        ? formatStatusMarker([ENTERPRISE_STATUS, BETA_STATUS])
+        : formatStatusMarker([BETA_STATUS]),
+  }
+
+  return { enterpriseFeature, betaBadge }
+}
+
+module.exports.createEnterpriseFeatureRules = createEnterpriseFeatureRules
+module.exports.formatStatusMarker = formatStatusMarker
+module.exports.ENTERPRISE_MARKER = ENTERPRISE_MARKER
+
 module.exports.register = function () {
   raiseListenerLimit(this)
   const logger = this.getLogger('convert-to-markdown-extension')
@@ -406,6 +516,11 @@ module.exports.register = function () {
       })
 
       // Markdown table conversion
+      // Keep the enterprise-license signal, which is otherwise CSS-only.
+      const enterpriseRules = createEnterpriseFeatureRules()
+      turndownInstance.addRule('enterprise-feature', enterpriseRules.enterpriseFeature)
+      turndownInstance.addRule('beta-badge', enterpriseRules.betaBadge)
+
       turndownInstance.addRule('tables', {
         filter: (node) => {
           if (node.nodeName !== 'TABLE') return false