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

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.

package/macros/badge.js

@@ -1,21 +1,43 @@
 'use strict';
 
+/**
+ * Build the HTML for a badge.
+ *
+ * Extracted from the macro body so other macros can render an identical badge
+ * without depending on the badge macro being registered in the consuming
+ * playbook. The enterprise macro uses it to render the beta badge for registry
+ * entries marked `beta: true`, which keeps one definition of the markup and
+ * the CSS class names.
+ *
+ * @param {object} opts
+ * @param {string} [opts.label] - Badge text.
+ * @param {string} [opts.size] - `large` renders without surrounding brackets.
+ * @param {string} [opts.tooltip] - Tooltip text, rendered as `data-tooltip`.
+ * @returns {string} Badge HTML.
+ */
+function buildBadgeHtml ({ label, size, tooltip } = {}) {
+  const text = label || 'label';
+  const className = `badge--${text.toLowerCase().replace(/\s+/g, '-')}`;
+  const isLarge = size === 'large';
+  const sizeClass = isLarge ? 'badge--large' : '';
+  const tooltipAttr = tooltip ? ` data-tooltip="${tooltip}"` : '';
+
+  // Add brackets if not large. The brackets matter beyond styling: they are
+  // real text content, so the label survives an HTML-to-Markdown conversion as
+  // "(beta)" rather than vanishing with the CSS class.
+  const renderedLabel = isLarge ? text : `(${text})`;
+
+  return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
+}
+
+module.exports.buildBadgeHtml = buildBadgeHtml;
+
 module.exports.register = function (registry) {
   registry.inlineMacro(function () {
     const self = this;
     self.named('badge');
-    self.process((parent, target, attrs) => {
-      const label = attrs.label || 'label';
-      const className = `badge--${label.toLowerCase().replace(/\s+/g, '-')}`;
-      const isLarge = attrs.size === 'large';
-      const sizeClass = isLarge ? 'badge--large' : '';
-      const tooltip = attrs.tooltip;
-      const tooltipAttr = tooltip ? ` data-tooltip="${tooltip}"` : '';
-
-      // Add brackets if not large
-      const renderedLabel = isLarge ? label : `(${label})`;
-
-      return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
-    });
+    self.process((parent, target, attrs) =>
+      buildBadgeHtml({ label: attrs.label, size: attrs.size, tooltip: attrs.tooltip })
+    );
   });
 };

package/macros/enterprise.js

@@ -0,0 +1,390 @@
+'use strict'
+
+/* Macros for marking and listing enterprise features.
+ *
+ * Inline macro — mark a feature in prose:
+ *
+ *   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 feature name renders as a uniquely styled term with a tooltip that
+ * explains the feature requires an Enterprise Edition license. The term
+ * links to the feature's documentation when an xref attribute is given,
+ * and otherwise to the licensing page, so readers can always reach an
+ * explanation of what having (or not having) a license means.
+ *
+ * Block macro — render the licensing feature table for one scope:
+ *
+ *   enterprise_features::redpanda[]
+ *   enterprise_features::connect[title=Enterprise features in Redpanda Connect]
+ *
+ * Registry validation:
+ *
+ * Both macros read the canonical enterprise features registry from the
+ * 'shared' component (modules/ROOT/partials/enterprise-features.yml in the
+ * shared folder of the docs repo). Inline targets are resolved against the
+ * registry case-insensitively, including aliases, and the canonical name,
+ * feature xref, and tooltip come from the matching entry. Unknown targets
+ * are reported according to the enterprise-validate attribute. When no
+ * registry is available (for example, outside an Antora build), the macros
+ * fall back to unvalidated rendering with a single warning.
+ *
+ * Document or site attributes:
+ *
+ *   enterprise-validate        'warn' (default) to log unknown feature names,
+ *                              'error' to fail the build, 'off' to disable
+ *                              validation.
+ *   enterprise-licensing-page  Resource ID of the licensing page used when
+ *                              no feature page is known
+ *                              (default: get-started:licensing/overview.adoc).
+ *   enterprise-feature-role    CSS class applied to the wrapping span
+ *                              (default: enterprise-feature).
+ *   enterprise-tooltip         'title' (default), 'true' (renders
+ *                              data-enterprise-tooltip), any attribute name
+ *                              starting with 'data-', or 'false' to disable.
+ *   enterprise-links           'true' (default) to render the term as a link.
+ *
+ * Example use in a playbook:
+ *
+ *   asciidoc:
+ *     extensions:
+ *     - '@redpanda-data/docs-extensions-and-macros/macros/enterprise'
+ */
+
+const yaml = require('js-yaml')
+const chalk = require('chalk')
+const { buildBadgeHtml } = require('./badge')
+
+const $enterpriseRegistry = Symbol('$enterpriseRegistry')
+
+const DEFAULT_LICENSING_PAGE = 'get-started:licensing/overview.adoc'
+const DEFAULT_ROLE = 'enterprise-feature'
+const BETA_LABEL = 'beta'
+
+/**
+ * Render the beta badge for a registry entry marked `beta: true`.
+ *
+ * The badge HTML is built directly rather than emitted as `badge:[...]`
+ * AsciiDoc, so it renders whether or not the consuming playbook registers the
+ * badge macro. Writing the macro call into a registry field used to be the only
+ * way to flag a beta feature, and it silently produced the literal text
+ * `badge::[label=beta]` in any build without that macro registered.
+ *
+ * @param {object} entry - Registry entry.
+ * @returns {string} Badge HTML, or an empty string when the entry is not beta.
+ */
+function buildBetaBadge (entry) {
+  if (!entry || entry.beta !== true) return ''
+  return buildBadgeHtml({
+    label: BETA_LABEL,
+    tooltip: entry['beta-tooltip'] || undefined,
+  })
+}
+
+/**
+ * The badge for a registry entry, wrapped for use in generated AsciiDoc.
+ *
+ * The block macro returns AsciiDoc source that Asciidoctor then parses, so raw
+ * HTML placed in a table cell is escaped and the reader sees the markup as
+ * text. An inline passthrough emits it verbatim instead, and unlike a
+ * `badge:[...]` macro call it does not require the badge macro to be registered
+ * in the consuming playbook.
+ *
+ * @param {object} entry - Registry entry.
+ * @returns {string} Passthrough-wrapped badge, or an empty string.
+ */
+function buildBetaBadgeAsciiDoc (entry) {
+  const html = buildBetaBadge(entry)
+  return html ? `pass:[${html}]` : ''
+}
+const REGISTRY_FILENAME = 'enterprise-features.yml'
+const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator', 'cloud']
+
+const TABLE_TITLES = {
+  redpanda: 'Enterprise features in Redpanda',
+  console: 'Enterprise features in Redpanda Console',
+  connect: 'Enterprise features in Redpanda Connect',
+  operator: 'Enterprise features in the Redpanda Operator',
+  cloud: 'Enterprise features in Redpanda Cloud',
+}
+
+const THIRD_COLUMN_HEADINGS = {
+  redpanda: 'Behavior Upon Expiration',
+  default: 'Restrictions Without Valid License',
+}
+
+let warnedNoRegistry = false
+
+/**
+ * Parse the registry YAML into a lookup structure. Exported for unit testing.
+ *
+ * @param {string} source - Raw YAML from enterprise-features.yml.
+ * @param {string} origin - Human-readable location for error messages.
+ * @returns {{features: object[], lookup: Map<string, object>}}
+ */
+function parseRegistry (source, origin = REGISTRY_FILENAME) {
+  const data = yaml.load(source)
+  if (!data || !Array.isArray(data.features)) {
+    throw new Error(`Enterprise features registry ${origin} has no 'features' list.`)
+  }
+  const lookup = new Map()
+  const claim = (rawKey, feature, kind) => {
+    const key = rawKey.trim().toLowerCase()
+    if (!key) return
+    const existing = lookup.get(key)
+    if (existing && existing !== feature) {
+      throw new Error(`Duplicate enterprise feature ${kind} '${rawKey}' in ${origin}: used by both '${existing.name}' and '${feature.name}'.`)
+    }
+    lookup.set(key, feature)
+  }
+  for (const feature of data.features) {
+    if (!feature || !feature.name) {
+      throw new Error(`Enterprise features registry ${origin} has an entry without a name.`)
+    }
+    if (feature.scope && !VALID_SCOPES.includes(feature.scope)) {
+      throw new Error(`Enterprise feature '${feature.name}' in ${origin} has unknown scope '${feature.scope}'.`)
+    }
+    claim(feature.name, feature, 'name')
+    for (const alias of feature.aliases || []) claim(String(alias), feature, 'alias')
+  }
+  return { features: data.features, lookup }
+}
+
+/**
+ * Load and cache the registry from the shared component in the Antora
+ * content catalog. Returns undefined when no registry is available.
+ */
+function loadRegistry (config) {
+  const contentCatalog = config && config.contentCatalog
+  if (!contentCatalog) return undefined
+  if (contentCatalog[$enterpriseRegistry] !== undefined) return contentCatalog[$enterpriseRegistry] || undefined
+  let registry = null
+  const partials = contentCatalog.findBy({ component: 'shared', module: 'ROOT', family: 'partial' }) || []
+  const registryFile = partials.find((file) => file.path && file.path.endsWith(REGISTRY_FILENAME))
+  if (registryFile) {
+    registry = parseRegistry(registryFile.contents.toString(), registryFile.path)
+  }
+  // Cache null too, so a missing registry is only searched for once per build.
+  contentCatalog[$enterpriseRegistry] = registry
+  return registry || undefined
+}
+
+function warnNoRegistry () {
+  if (warnedNoRegistry) return
+  warnedNoRegistry = true
+  console.warn(chalk.yellow(`Enterprise features registry (${REGISTRY_FILENAME} in the shared component) not found; enterprise: targets are not validated.`))
+}
+
+/**
+ * Report an unknown feature name according to the enterprise-validate mode.
+ */
+function reportUnknownFeature ({ feature, mode, registry, filePath }) {
+  if (mode === 'off') return
+  const candidates = registry.features
+    .map((entry) => entry.name)
+    .filter((name) => name.toLowerCase().includes(feature.trim().toLowerCase().split(/\s+/)[0] || ''))
+    .slice(0, 3)
+  const hint = candidates.length ? ` Did you mean: ${candidates.join(', ')}?` : ''
+  const where = filePath ? ` in ${filePath}` : ''
+  const message = `enterprise:${feature}[] does not match any feature in the enterprise features registry${where}.${hint} Add the feature to ${REGISTRY_FILENAME} in the shared component first.`
+  if (mode === 'error') throw new Error(message)
+  console.warn(chalk.yellow(message))
+}
+
+/**
+ * Pick the environment-appropriate feature page from a registry entry.
+ * Some features have separate documentation for Kubernetes, Linux
+ * (self-managed), and Redpanda Cloud. Mirrors the config_ref macro's
+ * environment-awareness: the env-cloud and env-kubernetes page attributes
+ * select the xref-cloud and xref-kubernetes registry fields, falling back
+ * to the default xref.
+ *
+ * @param {object} entry - Registry entry.
+ * @param {object} document - Asciidoctor document (for env attributes).
+ * @returns {string|undefined}
+ */
+function resolveEntryXref (entry, document) {
+  if (!entry) return undefined
+  if (document.getAttribute('env-cloud') !== undefined && entry['xref-cloud']) return entry['xref-cloud']
+  if (document.getAttribute('env-kubernetes') !== undefined && entry['xref-kubernetes']) return entry['xref-kubernetes']
+  return entry.xref
+}
+
+/**
+ * Resolve the tooltip attribute name from the enterprise-tooltip document
+ * attribute. Mirrors the glossary macro's contract.
+ *
+ * @param {string|undefined} raw - Raw attribute value.
+ * @returns {string|undefined} Attribute name to emit, or undefined when disabled.
+ */
+function resolveTooltipAttribute (raw) {
+  if (raw === 'false') return undefined
+  if (raw === undefined || raw === 'title') return 'title'
+  if (raw === 'true') return 'data-enterprise-tooltip'
+  if (raw.startsWith('data-')) return raw
+  console.warn(`enterprise-tooltip attribute '${raw}' must be 'title', 'true', 'false', or start with 'data-'. Falling back to 'title'.`)
+  return 'title'
+}
+
+/**
+ * Build the AsciiDoc content emitted for one inline macro instance. Exported
+ * for unit testing.
+ *
+ * @param {object} opts
+ * @param {string} opts.feature - Canonical feature name.
+ * @param {string} [opts.text] - Display text override.
+ * @param {string} [opts.xref] - Resource ID of the feature documentation.
+ * @param {string} [opts.url] - Absolute link used when no xref exists.
+ * @param {string} [opts.tooltip] - Tooltip text override.
+ * @param {string} opts.licensingPage - Resource ID of the licensing page.
+ * @param {string} opts.role - CSS class for the wrapping span.
+ * @param {string|undefined} opts.tooltipAttr - Tooltip attribute name, or undefined to omit.
+ * @param {boolean} opts.links - Whether to render a link.
+ * @returns {string}
+ */
+function buildEnterpriseContent ({ feature, text, xref, url, tooltip, licensingPage, role, tooltipAttr, links }) {
+  const display = text || feature
+  const tooltipText = tooltip || `${feature} requires an Enterprise Edition license.`
+  const escapedTooltip = tooltipText.replace(/"/g, '&quot;')
+  const tooltipHtml = tooltipAttr ? ` ${tooltipAttr}="${escapedTooltip}"` : ''
+  let inner = display
+  if (links) {
+    inner = xref ? `xref:${xref}[${display}]` : (url ? `link:${url}[${display}]` : `xref:${licensingPage}[${display}]`)
+  }
+  return `<span class="${role}"${tooltipHtml}>${inner}</span>`
+}
+
+/**
+ * Build the AsciiDoc source of the licensing feature table for one scope.
+ * Exported for unit testing.
+ *
+ * @param {object[]} features - All registry entries.
+ * @param {string} scope - Scope to render.
+ * @param {object} [opts]
+ * @param {string} [opts.title] - Table title override.
+ * @param {string} [opts.heading] - Third column heading override.
+ * @returns {string}
+ */
+function buildFeatureTable (features, scope, opts = {}) {
+  const rows = features
+    .filter((feature) => feature.scope === scope)
+    .sort((a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base' }))
+  const title = opts.title || TABLE_TITLES[scope]
+  const heading = opts.heading || THIRD_COLUMN_HEADINGS[scope] || THIRD_COLUMN_HEADINGS.default
+  const lines = [`.${title}`, '[cols="1a,2a,2a"]', '|===', `| Feature | Description | ${heading}`, '']
+  for (const feature of rows) {
+    let cell = feature.xref
+      ? `xref:${feature.xref}[${feature.name}]`
+      : (feature.url ? `link:${feature.url}[${feature.name}]` : feature.name)
+    if (feature['feature-suffix']) cell += ` ${feature['feature-suffix']}`
+    const betaBadge = buildBetaBadgeAsciiDoc(feature)
+    if (betaBadge) cell += ` ${betaBadge}`
+    if (feature['show-gating-property'] && feature['gating-property']) cell += `\n(\`${feature['gating-property']}\`)`
+    lines.push(`| ${cell}`)
+    lines.push(`| ${(feature.description || '').trim()}`)
+    lines.push(`| ${(feature.expiration || '').trim()}`)
+    lines.push('')
+  }
+  lines.push('|===')
+  return lines.join('\n')
+}
+
+function enterpriseInlineMacro (config) {
+  return function () {
+    const self = this
+    self.named('enterprise')
+    // Specifying the regexp allows spaces in the feature name.
+    self.$option('regexp', /enterprise:([^[]+)\[(|.*?[^\\])\]/)
+    self.process(function (parent, target, attributes) {
+      const document = parent.getDocument()
+      let registry
+      if (config && config.contentCatalog) {
+        registry = loadRegistry(config)
+        if (!registry) warnNoRegistry()
+      }
+      let feature = target
+      let entry
+      if (registry) {
+        entry = registry.lookup.get(target.trim().toLowerCase())
+        if (entry) {
+          feature = entry.name
+        } else {
+          reportUnknownFeature({
+            feature: target,
+            mode: document.getAttribute('enterprise-validate', 'warn'),
+            registry,
+            filePath: config && config.file && config.file.src && config.file.src.path,
+          })
+        }
+      }
+      let content = buildEnterpriseContent({
+        feature,
+        text: attributes.text,
+        xref: attributes.xref || resolveEntryXref(entry, document),
+        url: entry && entry.url,
+        tooltip: attributes.tooltip || (entry && entry.tooltip) || undefined,
+        licensingPage: document.getAttribute('enterprise-licensing-page', DEFAULT_LICENSING_PAGE),
+        role: document.getAttribute('enterprise-feature-role', DEFAULT_ROLE),
+        tooltipAttr: resolveTooltipAttribute(document.getAttribute('enterprise-tooltip')),
+        links: document.getAttribute('enterprise-links', 'true') === 'true',
+      })
+      // A feature marked beta in the registry is beta wherever it is
+      // referenced, so prose gets the same badge as the generated tables.
+      // Set enterprise-beta-badge to false to suppress it in prose only.
+      if (document.getAttribute('enterprise-beta-badge', 'true') === 'true') {
+        const betaBadge = buildBetaBadge(entry)
+        if (betaBadge) content += ` ${betaBadge}`
+      }
+      // The xref inside the span is resolved by the 'macros' substitution,
+      // the same mechanism the config_ref macro relies on.
+      return self.createInline(parent, 'quoted', content, { attributes: { subs: 'macros' } })
+    })
+  }
+}
+
+function enterpriseFeaturesBlockMacro (config) {
+  return function () {
+    const self = this
+    self.named('enterprise_features')
+    self.process(function (parent, target, attributes) {
+      const scope = (target || attributes.scope || '').trim()
+      if (!VALID_SCOPES.includes(scope)) {
+        throw new Error(`enterprise_features::[] needs a scope of ${VALID_SCOPES.join(', ')} as its target, got '${scope}'.`)
+      }
+      const registry = config && config.contentCatalog ? loadRegistry(config) : undefined
+      if (!registry) {
+        warnNoRegistry()
+        return self.parseContent(parent, `WARNING: The enterprise features registry is unavailable, so the ${scope} feature table cannot be rendered.`)
+      }
+      const table = buildFeatureTable(registry.features, scope, { title: attributes.title, heading: attributes.heading })
+      // A block anchor before the macro call ([[my-id]]) is consumed into the
+      // macro's id attribute. Re-emit it so crossrefs to the table keep working.
+      const source = attributes.id ? `[[${attributes.id}]]\n${table}` : table
+      return self.parseContent(parent, source)
+    })
+  }
+}
+
+function register (registry, config = {}) {
+  if (typeof registry.register === 'function') {
+    registry.register(function () {
+      this.inlineMacro(enterpriseInlineMacro(config))
+      this.blockMacro(enterpriseFeaturesBlockMacro(config))
+    })
+  } else if (typeof registry.inlineMacro === 'function') {
+    registry.inlineMacro(enterpriseInlineMacro(config))
+    if (typeof registry.blockMacro === 'function') registry.blockMacro(enterpriseFeaturesBlockMacro(config))
+  } else {
+    console.warn("no 'inlineMacro' method on alleged registry")
+  }
+  return registry
+}
+
+module.exports.register = register
+module.exports.buildEnterpriseContent = buildEnterpriseContent
+module.exports.buildFeatureTable = buildFeatureTable
+module.exports.parseRegistry = parseRegistry
+module.exports.resolveEntryXref = resolveEntryXref
+module.exports.resolveTooltipAttribute = resolveTooltipAttribute