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

package/bin/doc-tools.js

@@ -827,6 +827,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
  *
@@ -2133,5 +2175,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/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

package/extensions/property-page-index.js

@@ -0,0 +1,44 @@
+'use strict'
+
+/* Antora extension that warms the prop macro's property-page index before
+ * document conversion starts.
+ *
+ * The prop macro discovers which reference page documents each property by
+ * reading page sources for include:: lines and partials for property
+ * headings. Antora replaces each page's contents with converted HTML as
+ * conversion proceeds, so an index built lazily by the first macro call can
+ * miss includes on pages that were converted earlier — the result silently
+ * depends on conversion order. Building the index at contentClassified,
+ * while every page still holds its AsciiDoc source, removes the ordering
+ * hazard entirely. The macro finds the warmed cache and never rebuilds it.
+ *
+ * Register under antora.extensions (NOT asciidoc.extensions):
+ *
+ *   antora:
+ *     extensions:
+ *     - require: '@redpanda-data/docs-extensions-and-macros/extensions/property-page-index'
+ */
+
+const { buildPageIndex, loadPropertiesFor } = require('../macros/prop')
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
+module.exports.register = function () {
+  raiseListenerLimit(this)
+  const logger = this.getLogger('property-page-index-extension')
+
+  this.once('contentClassified', ({ contentCatalog }) => {
+    let indexed = 0
+    for (const component of contentCatalog.getComponents()) {
+      for (const componentVersion of component.versions) {
+        const registry = loadPropertiesFor(contentCatalog, component.name, componentVersion.version)
+        if (!registry) continue
+        const index = buildPageIndex(contentCatalog, component.name, registry.properties, componentVersion.version)
+        if (index.size > 0) {
+          indexed++
+          logger.debug(`Indexed ${index.size} properties for ${component.name}@${componentVersion.version || 'default'}`)
+        }
+      }
+    }
+    if (indexed > 0) logger.info(`Property page index warmed for ${indexed} component version(s)`)
+  })
+}

package/extensions/validate-attributes.js

@@ -68,7 +68,7 @@ function validateCategories(pageCategoryList, pageInfo, categoryMap, logger) {
   });
 
   if (!isValid) {
-      logger.warn(`Invalid categories detected. For a list of valid categories, see https://github.com/redpanda-data/docs/tree/shared/modules/ROOT/partials/valid-categories.yml`);
+      logger.warn(`Invalid categories detected. For a list of valid categories, see https://github.com/redpanda-data/docs/blob/main/shared/modules/ROOT/partials/valid-categories.yml`);
   }
   return Array.from(adjustedCategories).join(', ');
 }

package/macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adoc

@@ -0,0 +1,90 @@
+= How property and enterprise references work
+:toc:
+:toclevels: 2
+
+A plain-English explanation of how the docs mark configuration properties and enterprise features, why it works this way, and what the tooling does for you. For attribute-by-attribute details, see link:REFERENCE.adoc[the macros reference].
+
+== The problem this solves
+
+The docs used to *guess*. Property tooltips decorated every piece of inline code whose text happened to match a property name. That works fine for a name like `cloud_storage_enabled`, but five real property names are ordinary words: `admin`, `brokers`, `rack`, `retries`, and `superusers`. On a Helm chart page, `admin` usually means an audit-logging setting or a listener name -- and readers still got a tooltip describing the Admin API broker property. Wrong information, delivered confidently.
+
+Enterprise feature mentions had the opposite problem: nothing checked them at all. Any writer could mark any feature as enterprise, under any name, and nothing would ever notice a typo, a made-up name, or a feature that isn't actually enterprise.
+
+The fix for both is the same idea: *marking is explicit, and every mark is checked against a source of truth at build time.*
+
+== Property references: the prop macro
+
+To reference a configuration property in prose, write:
+
+[,asciidoc]
+----
+prop:cloud_storage_enabled[]
+----
+
+That's it. Here's what happens for you:
+
+*It's checked.* The name is looked up in the published property data -- the same JSON, generated from Redpanda's source code, that powers the reference pages and tooltips. A typo gets a build warning with the file name and a "did you mean" suggestion. Nothing unverified ships. (A site can turn this up to a hard build failure with the `property-validate` attribute.)
+
+*It gets a tooltip.* The docs UI decorates only elements the macro marked. A plain backticked word never gets a tooltip anymore, so `admin` in a Helm example stays plain text unless a writer deliberately writes `prop:admin[]`.
+
+*It can link itself.* Add `link=true` and the property links to its reference page. You don't say which page -- the build works that out by looking at which reference page actually documents that property (details below). If our property reference is ever reorganized into different pages, every link follows automatically.
+
+*It adapts to Kubernetes pages.* Add `helm-path=auto` and, on pages rendered for Kubernetes, the property displays as the Helm values path readers actually type -- `config.cluster.log_segment_size`, `config.node.fips_mode`, or `storage.tiered.config.cloud_storage_enabled` for tiered storage settings. On Linux pages the same call shows the plain name. One sentence, correct for both audiences.
+
+*Once per paragraph is enough.* Mark the first mention of a property in a paragraph and leave later mentions as plain backticks -- a paragraph doesn't need three identical tooltips. The migration tool follows this rule, and the UI enforces it as a backstop: even if every mention is marked, only the first one per paragraph gets the tooltip.
+
+=== How "the build works out the page" (dynamic discovery)
+
+Rather than hardcoding "cluster properties live on the cluster-properties page," the macro reads the actual docs during the build. Every documented property appears as a heading in the generated property files, and each reference page pulls in one or more of those files. The macro follows that chain -- which pages exist, what they include, which property headings end up where -- and builds a lookup table per doc set.
+
+Because the lookup is done separately for each part of the site, a Cloud page links to Cloud's own property pages and a streaming page to streaming's. Cloud reuses streaming's property files with a filter ("only the cloud-relevant parts"), and the macro applies that same filter, so it never links to a property that a given page doesn't actually document. If a doc set doesn't cover a property at all -- Cloud publishes no topic-properties page, Connect publishes none -- the link borrows the streaming docs instead of pointing nowhere.
+
+Think phone book, not memory: if a property moves, the next build's phone book is already right.
+
+=== What happened to config_ref
+
+The old `config_ref` macro did a smaller version of this job with three problems: you had to tell it which page to link to by hand, it never checked the property name, and on Kubernetes pages it prefixed *every* property with `storage.tiered.config.` -- which is only correct for tiered storage settings. The live docs really did render `storage.tiered.config.log_segment_size`, a path that mislabels where that setting belongs.
+
+`config_ref` is deprecated. Every hand-written call site has been converted, the property extractor now emits `prop` in generated content, and the published JSON was cleaned up (it had been leaking raw macro text into tooltips). The macro stays registered only because older versioned docs, which are frozen, still contain it. Don't write it in new content.
+
+=== Migrating existing content
+
+One command converts a repo's prose:
+
+[,bash]
+----
+npx doc-tools generate migrate-property-refs \
+  --properties modules/reference/attachments/redpanda-properties-<tag>.json \
+  --config-refs
+----
+
+It's a dry run by default; add `--write` to apply. It only converts names it can verify in the published JSON, never touches the five ambiguous word-like names, and skips code blocks, headings, generated content, and anything already inside another macro.
+
+One thing no tool can check: *meaning*. Marking a name asserts "this mention refers to the Redpanda property" -- and even distinctive names collide in foreign-vocabulary contexts. A Terraform provider table's `replication.factor` argument, a SQL statement's `cluster_id` parameter, or an infrastructure checklist's `cloud_storage_bucket` are other systems' identifiers that happen to share a spelling. When reviewing a migration, unmark those. When writing, only reach for `prop:` when a tooltip describing the Redpanda property would help the reader in that sentence.
+
+== Enterprise feature references: the enterprise macro
+
+The same explicit-and-checked idea, for licensing:
+
+[,asciidoc]
+----
+enterprise:Tiered Storage[]
+----
+
+The name is validated against the *enterprise features registry* -- a single YAML file in the shared component (`shared/modules/ROOT/partials/enterprise-features.yml` in the docs repo) that is the canonical list of what is enterprise and what each feature is called externally. Writers can't misname a feature (aliases and case differences resolve to the canonical name, and internal engineering names like `cloud_storage` render as their proper external name) and can't mark something enterprise that isn't in the registry. Adding a feature to the registry is a reviewed docs change, and each entry records *why* it's enterprise by pointing at the internal source of truth (a license-gate in Redpanda's source, the Connect plugin catalog, or a written justification).
+
+Two more things come from the same registry:
+
+* The licensing feature tables on the licensing pages are *generated* from it (`enterprise_features::redpanda[]` and friends), so the tables can never disagree with the registry.
+* `doc-tools validate enterprise-features` compares the registry against the actual license gates in Redpanda's source code and Connect's plugin list. When engineering ships a new license-gated feature, CI fails until someone decides its documented name -- naming stays a human decision, but forgetting is no longer possible.
+
+Like properties, feature links adapt to context: registry entries can carry Kubernetes- and Cloud-specific pages, chosen by the page's environment attributes.
+
+== Where to see all of this working
+
+* The extensions preview site's test page demonstrates every form of both macros, including intentional failure cases, and a Kubernetes-environment page shows the environment-specific behavior side by side.
+* The docs-ui preview's `property-tooltips-test` and `enterprise-macro-test` pages show every output shape the UI styles, including the negative cases (unmarked names must get nothing).
+
+== The one-sentence version
+
+Nothing in the docs claims a name is a property or a feature is enterprise unless a writer said so explicitly *and* the build verified it against the source of truth.

package/macros/README.adoc

@@ -10,6 +10,8 @@ AsciiDoc macros are custom inline and block elements that extend AsciiDoc syntax
 
 == Documentation
 
+link:PROPERTY_AND_ENTERPRISE_REFERENCES.adoc[**How property and enterprise references work**]:: Plain-English explanation of the prop and enterprise macros: explicit marking, build-time validation against sources of truth, dynamic link discovery, and why config_ref was deprecated
+
 link:USER_GUIDE.adoc[**User guide**]:: How to use AsciiDoc macros in your documentation
 +
 * Installation and setup

package/macros/REFERENCE.adoc

@@ -20,6 +20,8 @@ antora:
 
 == config_ref
 
+IMPORTANT: `config_ref` is deprecated. The <<prop>> macro supersedes all of its functionality: it validates names against the published property reference, discovers the target page dynamically instead of taking a manual path, powers hover tooltips, and its `helm-path=auto` attribute replaces `config_ref`'s Kubernetes prefixing with a per-property correct Helm values path (`config_ref` prefixed every property with `storage.tiered.config.`, mislabeling non-tiered properties). Migrate call sites with `doc-tools generate migrate-property-refs --config-refs`. The macro stays registered only because the generated property partials still emit it.
+
 This inline macro is used to generate a reference to a configuration value in the Redpanda documentation. The macro's parameters allow for control over the generated reference's format and the type of output produced.
 
 === Usage
@@ -62,6 +64,171 @@ asciidoc:
     - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
 ----
 
+== enterprise
+
+This inline macro marks a feature as an enterprise feature in prose. The feature name renders as a uniquely styled term with a tooltip explaining that the feature requires an Enterprise Edition license, and links to the feature's documentation or to the licensing page.
+
+The macro validates its target against the enterprise features registry: `modules/ROOT/partials/enterprise-features.yml` in the `shared` component (the `shared/` folder of the docs repository). The registry is the canonical list of enterprise features and their approved external names. Targets are matched case-insensitively, including aliases, and the canonical name, feature page link, and tooltip come from the matching entry. A target that matches no entry is reported according to `enterprise-validate`. To mark a new feature as enterprise, add it to the registry first.
+
+=== Usage
+
+[,asciidoc]
+----
+enterprise:Continuous Data Balancing[]
+enterprise:Tiered Storage[xref=manage:tiered-storage.adoc]
+enterprise:Audit Logging[text=audit logging]
+enterprise:Iceberg Topics[tooltip=Iceberg Topics requires an Enterprise Edition license and object storage.]
+----
+
+The macro target is the feature name, which can contain spaces. Named attributes:
+
+xref::
+Optional Antora resource ID of the feature's documentation page. Overrides the registry entry's link. When neither is set, the term links to the licensing page.
++
+Registry entries can carry environment-specific pages: on pages with the `env-cloud` attribute the entry's `xref-cloud` is used, on pages with `env-kubernetes` the entry's `xref-kubernetes` is used, and otherwise the entry's default `xref` (the Linux or generic self-managed page). This mirrors the `config_ref` macro's environment awareness.
+
+text::
+Optional display text override. Use it when the sentence needs different casing or phrasing than the feature name.
+
+tooltip::
+Optional tooltip text override. Overrides the registry entry's `tooltip`. The default is `<feature> requires an Enterprise Edition license.`
+
+=== Configuration options
+
+enterprise-validate::
+How to report a target that does not match any registry entry: `warn` (default) logs a build warning with the file path and close-match suggestions, `error` fails the build, and `off` disables validation. When no registry is available in the build, the macro renders without validation and logs a single warning.
+
+enterprise-licensing-page::
+Resource ID of the licensing page used when no `xref` attribute is given. The default is `get-started:licensing/overview.adoc`.
+
+enterprise-feature-role::
+CSS class applied to the wrapping span. The default is `enterprise-feature`. Style this class in the UI bundle to give enterprise terms a consistent visual treatment.
+
+enterprise-tooltip::
+Controls the tooltip attribute: `title` (default), `true` (renders `data-enterprise-tooltip` for UI-driven tooltips), any attribute name starting with `data-`, or `false` to disable tooltips.
+
+enterprise-links::
+Set to `false` to render the term without a link.
+
+enterprise-beta-badge::
+Set to `false` to suppress the beta badge in prose. Generated tables always show it. See <<beta-features>>.
+
+[[beta-features]]
+=== Beta features
+
+Add `beta: true` to a registry entry to mark the feature as beta. The macro then renders a beta badge after the feature name, both in prose and in the generated `enterprise_features` tables, so one registry field keeps every reference consistent:
+
+[,yaml]
+----
+- name: Stretch Clusters
+  scope: operator
+  beta: true
+  feature-suffix: (StretchCluster resource)
+----
+
+Add `beta-tooltip` to give the badge hover text.
+
+Do not write a `badge:` macro call into `feature-suffix` to achieve this. The badge is emitted as an inline passthrough, so it renders whether or not the consuming playbook registers the `badge` macro, and it degrades to the text `(beta)` in Markdown. A hand-written macro call renders as literal source text in any build that does not register that macro.
+
+=== Markdown output
+
+In HTML, the enterprise signal is carried by the span's CSS class and its tooltip attribute. Both are attributes, so an HTML-to-Markdown conversion drops them and the term arrives as an ordinary feature name. To keep the signal for readers of the Markdown pages, including AI agents, the `convert-to-markdown` extension appends an explicit `(enterprise)` marker and preserves any link:
+
+[,markdown]
+----
+Enable [Tiered Storage](../manage/tiered-storage.md) (enterprise) today.
+----
+
+A feature that is also marked `beta: true` gets one combined marker rather than two adjacent parentheticals:
+
+[,markdown]
+----
+Enable [Stretch Clusters](../deploy/stretch-clusters.md) (enterprise, beta) today.
+----
+
+This applies to the inline macro. The tables from `enterprise_features` need no enterprise marker, because their expiration column already states the licensing behavior as text. A beta badge in a table converts to `(beta)` on its own.
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/enterprise'
+----
+
+== enterprise_features
+
+This block macro renders the licensing feature table for one scope from the enterprise features registry (see <<enterprise>>). Because the table is generated, it can never drift from the registry.
+
+=== Usage
+
+[,asciidoc]
+----
+enterprise_features::redpanda[]
+enterprise_features::connect[]
+enterprise_features::operator[title=Operator features,heading=What stops working]
+----
+
+The target is the scope: `redpanda`, `console`, `connect`, `operator`, or `cloud`. Rows render alphabetically by feature name with three columns: the feature name (linked to its documentation page when the entry has an `xref` or `url`), the description, and the expiration or restriction behavior. Named attributes:
+
+title::
+Optional table title override. The default is scope-specific, for example `Enterprise features in Redpanda`.
+
+heading::
+Optional third-column heading override. The default is `Behavior Upon Expiration` for the `redpanda` scope and `Restrictions Without Valid License` for the other scopes.
+
+=== Registration
+
+Registered together with the `enterprise` inline macro (see <<enterprise>>).
+
+== prop
+
+This inline macro references a Redpanda configuration property in prose. The property renders as a marked `<code>` element (`property-ref` class plus a `data-property-name` attribute) that the docs UI decorates with a hover-documentation tooltip. Marking is opt-in: only properties referenced through this macro get tooltips, so ambiguous words such as `admin` or `rack` in unrelated contexts (Helm values, feature settings) are never decorated by mistake.
+
+The macro validates its target against the published property reference: the newest `redpanda-properties-<tag>.json` attachment in the `reference` module of the build, the same data the tooltips fetch at runtime. To migrate existing plain-backtick property mentions, use `doc-tools generate migrate-property-refs`.
+
+=== Usage
+
+[,asciidoc]
+----
+prop:cloud_storage_enabled[]
+prop:iceberg_enabled[link=true]
+prop:retention_ms[link=true,page=properties/topic-properties]
+prop:write_caching_default[text=write caching]
+----
+
+The macro target is the property name. Named attributes:
+
+link::
+Set to `true` to also link the property to its reference page. The page is discovered dynamically: the macro indexes which reference-module page in the current component documents each property, by scanning property headings in the partials each page includes (respecting include tag filters such as `tags=redpanda-cloud`). Links are component-relative, so a Cloud page links to the Cloud component's own property pages, and they keep working if properties are split across different pages in the future. When discovery finds nothing, the page falls back deterministically to the property's `config_scope` (`cluster`, `broker`, or `topic`). This supersedes the `config_ref` macro's linking for most uses.
+
+page::
+Optional reference-page override (module-relative, without `.adoc`), for example `properties/object-storage-properties`. Overrides discovery entirely.
+
+helm-path::
+Set to `auto` to display the property as its Helm values path on pages rendered with the `env-kubernetes` attribute, so single-sourced content reads correctly for both Linux and Kubernetes audiences. The path is derived per property: `storage.tiered.config.<name>` for tiered storage properties, `config.node.<name>` for broker properties, and `config.cluster.<name>` for other cluster properties. On pages without `env-kubernetes`, the plain property name renders. This supersedes the deprecated `config_ref` macro's prefixing.
+
+text::
+Optional display text override. Wins over the Helm path display.
+
+=== Configuration options
+
+property-validate::
+How to report a target that does not match any published property: `warn` (default) logs a build warning with the file path and close-match suggestions, `error` fails the build, and `off` disables validation. When no property JSON is available in the build, the macro renders without validation and logs a single warning.
+
+property-ref-role::
+CSS class applied to the code element. The default is `property-ref`.
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/prop'
+----
+
 == glossterm
 
 The `glossterm` inline macro provides a way to define and reference glossary terms in your AsciiDoc documents.