@redpanda-data/docs-extensions-and-macros 5.12.0 → 5.12.1

package/extensions/set-available-attachment-versions.js

@@ -2,7 +2,12 @@
 
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
 
-const semver = require('semver')
+// The same comparator the prop macro uses to pick a dataset. semver.coerce
+// keeps 'rc10' as one alphanumeric identifier and string-compares it, so it
+// ranked v26.3.1-rc2 above v26.3.1-rc10 while the macro ranked them correctly:
+// build-time validation and the runtime tooltip fetch would then read different
+// files. Sharing the comparator is the only way they cannot disagree.
+const { compareTags } = require('../macros/prop')
 
 /**
  * Points UI templates at generated JSON attachments that actually exist.
@@ -19,7 +24,9 @@ const semver = require('semver')
  * component version:
  *
  * - available-properties-tag: newest redpanda-properties-<tag>.json attachment
- *   in the reference module of each streaming (ROOT) component version
+ *   in the reference module of a component version that publishes property
+ *   data (the ROOT and streaming components, plus any component shipping such
+ *   an attachment of its own)
  * - available-connect-version: newest connect-<version>.json attachment in the
  *   components module of the connect component
  * - page-disable-property-tooltips: 'true' on streaming versions that have no
@@ -54,8 +61,19 @@ module.exports.register = function () {
       if (!isProperties && !isConnect) return
 
       component.versions.forEach((compVer) => {
-        const attributes = ((compVer.asciidoc = compVer.asciidoc || {}).attributes =
-          compVer.asciidoc.attributes || {})
+        // Copy before writing. Antora hands every component version whose
+        // antora.yml declares no `asciidoc:` block THE SAME siteAsciiDocConfig
+        // object -- see the NOTE at content-classifier/lib/content-catalog.js
+        // ("if no AsciiDoc attributes are defined in the component descriptor,
+        // asciidoc is the siteAsciiDocConfig object"). Mutating it in place
+        // wrote these attributes into the shared site config, so a component
+        // publishing no property data still advertised a dataset, and because
+        // the write is guarded on the attribute being unset, the first version
+        // processed won and every later version silently kept that value --
+        // no log line, and the wrong tag. Cloning both levels makes the write
+        // per-version, which is what the attribute means.
+        const asciidoc = (compVer.asciidoc = { ...compVer.asciidoc })
+        const attributes = (asciidoc.attributes = { ...asciidoc.attributes })
         const attachments = contentCatalog.findBy({
           component: component.name,
           version: compVer.version,
@@ -98,17 +116,13 @@ module.exports.register = function () {
 
 function findNewestVersion (attachments, module, rx) {
   let newestRaw = null
-  let newestSemver = null
   attachments.forEach((attachment) => {
     if (attachment.src.module !== module) return
     const basename = attachment.src.relative.split('/').pop()
     const match = basename.match(rx)
     if (!match) return
     const raw = match[1]
-    const parsed = semver.coerce(raw, { includePrerelease: true })
-    if (!parsed) return
-    if (!newestSemver || semver.gt(parsed, newestSemver)) {
-      newestSemver = parsed
+    if (!newestRaw || compareTags(raw, newestRaw) > 0) {
       newestRaw = raw
     }
   })

package/macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adoc

@@ -31,7 +31,7 @@ Every release series has its own copy of that data, and the build picks the copy
 
 *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.
+*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, as does a topic property anywhere: topic properties are set per topic rather than in `values.yaml`, so there is no path to show. 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.
 
@@ -41,9 +41,11 @@ Rather than hardcoding "cluster properties live on the cluster-properties page,"
 
 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, and a link is only ever emitted when a page in that same doc set actually documents the property. Nothing is linked across doc sets, and no page is guessed from a property's scope -- a link the build can't verify is a broken link.
 
-Availability is a separate question from linking, and it comes from the data rather than from which pages happen to include what. The published JSON marks each property with `cloud_supported`. Cloud is managed Redpanda, so a Cloud page may reference only the properties that flag covers, and it always reads the newest self-managed file: there is no such thing as a Cloud release of the property list. A property Cloud doesn't support renders as plain code in code font -- no link and no tooltip -- plus a build warning naming the property and the file. A tooltip there would tell a Cloud reader they can change something they can't. (`cloud_supported` is the whole gate: no published property is editable or read-only in Cloud without also being supported.)
+Availability is a separate question from linking, and it comes from the data rather than from which pages happen to include what. Cloud is managed Redpanda, so it has no property release of its own: a Cloud page reads the newest *released* self-managed file, ignoring release candidates, because Cloud runs released Redpanda.
 
-Usefully, the current data has no Cloud-supported *topic* property at all -- all 62 are cluster properties. So a topic property mentioned on a Cloud page isn't a missing page; it genuinely doesn't apply.
+What that file can rule out is narrower than it looks. `cloud_supported` is derived from the Cloud control plane's install pack, and that source describes *cluster* configuration and nothing else. So the gate applies to cluster properties only: a cluster property the control plane forbids renders as plain code -- no link and no tooltip -- plus a build warning naming the property and the file, because a tooltip there would tell a Cloud reader they can change something they can't. For any other scope the file has no opinion, and a mention is allowed. Topic properties in particular are set per topic through the Kafka API, rpk, or Console -- a surface the control plane doesn't gate -- and Cloud publishes a topic properties reference of its own.
+
+An absent `cloud_supported` therefore means "not asserted", not "unsupported". Only an explicit `false` on a cluster property blocks a mention. (Where the flag is written, it is self-consistent: no published property is editable or read-only in Cloud without also being supported.)
 
 Doc sets with no property data -- Connect, the agentic data plane -- get nothing, and nothing is inferred for them. Their version numbers are their own product's, and say nothing about which Redpanda properties exist. Adding a third doc set is a deliberate change to the macro, not something it guesses.
 

package/macros/REFERENCE.adoc

@@ -20,7 +20,7 @@ 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.
+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 older versioned docs, which are frozen, still contain it; generated content emits `prop` (the extractor rewrites any `config_ref` it finds).
 
 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.
 
@@ -46,7 +46,7 @@ This is the path to the document where the configuration value is defined. This
 
 IMPORTANT: The path must be the name of a document at the root of the `reference` module.
 
-NOTE: The `config_ref` macro is environment-aware. It checks if the document it is being used in is part of a Kubernetes environment by checking if the `env-kubernetes` attribute is set in the document's attributes. Depending on this check, it either prepends `storage.tieredConfig.` to the `configRef` or just uses the `configRef` as is.
+NOTE: The `config_ref` macro is environment-aware. It checks if the document it is being used in is part of a Kubernetes environment by checking if the `env-kubernetes` attribute is set in the document's attributes. Depending on this check, it either prepends `storage.tiered.config.` to the `configRef` or just uses the `configRef` as is.
 
 For example:
 
@@ -184,7 +184,7 @@ asciidoc:
 
 == 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.
+This block macro renders the licensing feature table for one scope from the enterprise features registry (see the `enterprise` macro above). Because the table is generated, it can never drift from the registry.
 
 === Usage
 
@@ -205,7 +205,7 @@ Optional third-column heading override. The default is `Behavior Upon Expiration
 
 === Registration
 
-Registered together with the `enterprise` inline macro (see <<enterprise>>).
+Registered together with the `enterprise` inline macro.
 
 == prop
 
@@ -219,20 +219,20 @@ The macro checks that a property is actually available to the audience reading t
 ----
 prop:cloud_storage_enabled[]
 prop:iceberg_enabled[link=true]
-prop:retention_ms[link=true,page=properties/topic-properties]
+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. See <<prop-undocumented>> for properties the current component does not document. This supersedes the `config_ref` macro's linking for most uses.
+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. See <<prop-availability>> for properties the current component does not document. 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.
+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 properties whose name begins `cloud_storage_`, `config.node.<name>` for broker properties, and `config.cluster.<name>` for cluster properties. Topic properties render as the plain name, because they are set per topic through the Kafka API, rpk, or a Topic resource and have no `values.yaml` key at all. The plain name also renders on any page where `env-kubernetes` is unset or explicitly `false`. This supersedes the deprecated `config_ref` macro's prefixing.
 
 text::
 Optional display text override. Wins over the Helm path display.
@@ -240,7 +240,7 @@ 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, the dataset the page was checked against, and close-match suggestions; `error` fails the build; and `off` disables validation and silences every warning described here. When no property JSON is available in the build, the macro renders without validation and logs one warning per component version.
+How to report a target that does not match any published property: `warn` (default) logs a build warning with the file path, the dataset the page was checked against, and close-match suggestions; `error` fails the build; and `off` disables validation and silences the unknown-name, unavailable-property, unpublished-property and missing-data warnings. Diagnostics about the build itself are not silenced by `off`, because they report a broken input rather than a questionable mention: unusable property JSON, a property claimed by two declared sources, and an index built after conversion started. When no property JSON is available in the build, the macro renders without validation and logs one warning per component version.
 
 [[prop-version-selection]]
 === Which property data a page validates against

package/macros/badge.js

@@ -15,30 +15,52 @@
  * @param {string} [opts.tooltip] - Tooltip text, rendered as `data-tooltip`.
  * @returns {string} Badge HTML.
  */
+// Hover text for the labels this macro is asked for by name. The badge is
+// styled with a help cursor, so a badge with nothing to say promises an
+// explanation and then withholds it. Callers with something more specific pass
+// their own tooltip, which wins.
+const DEFAULT_TOOLTIPS = {
+  beta: 'This feature is in public beta. You can enable it, but it may change before it is generally available.',
+  unreleased: 'This feature is not in a released version of Redpanda yet. It is documented here for the upcoming release.',
+};
+
 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' : '';
-  // Escape before interpolating: tooltips come from a registry field, and an
-  // unescaped quote terminates the attribute early, turning the rest of the
-  // text into stray attributes (including event handlers).
+  // Escape before interpolating: these values reach the macro from .adoc source
+  // and from registry fields, and an unescaped quote terminates the attribute
+  // early, turning the rest of the text into stray attributes (including event
+  // handlers). The label needs it as much as the tooltip -- it lands in the
+  // class attribute and in the text content, and escaping only the tooltip left
+  // `badge:x[label=x" onmouseover="...]` free to break out of the class.
   const escapeAttr = (value) => String(value)
     .replace(/&/g, '&')
     .replace(/"/g, '"')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;');
-  const tooltipAttr = tooltip ? ` data-tooltip="${escapeAttr(tooltip)}"` : '';
+  const className = `badge--${escapeAttr(text.toLowerCase().replace(/\s+/g, '-'))}`;
+  // hasOwnProperty, not a bare index: `label=constructor` and `label=__proto__`
+  // are already lowercase, so a bare lookup shipped
+  // `function Object() { [native code] }` to readers as hover text. prop.js
+  // guards its property lookups the same way.
+  const labelKey = text.trim().toLowerCase();
+  const defaultTooltip = Object.prototype.hasOwnProperty.call(DEFAULT_TOOLTIPS, labelKey)
+    ? DEFAULT_TOOLTIPS[labelKey]
+    : undefined;
+  const hoverText = tooltip || defaultTooltip;
+  const tooltipAttr = hoverText ? ` data-tooltip="${escapeAttr(hoverText)}"` : '';
 
   // 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})`;
+  const renderedLabel = isLarge ? escapeAttr(text) : `(${escapeAttr(text)})`;
 
   return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
 }
 
 module.exports.buildBadgeHtml = buildBadgeHtml;
+module.exports.DEFAULT_TOOLTIPS = DEFAULT_TOOLTIPS;
 
 module.exports.register = function (registry) {
   registry.inlineMacro(function () {

package/macros/enterprise.js

@@ -55,9 +55,10 @@
 
 const yaml = require('js-yaml')
 const chalk = require('chalk')
-const { buildBadgeHtml } = require('./badge')
+const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
 
 const $enterpriseRegistry = Symbol('$enterpriseRegistry')
+const $enterpriseRegistryUnreadable = Symbol('$enterpriseRegistryUnreadable')
 const $warned = Symbol('$warned')
 
 /**
@@ -76,8 +77,10 @@ const DEFAULT_LICENSING_PAGE = 'get-started:licensing/overview.adoc'
 const DEFAULT_ROLE = 'enterprise-feature'
 const BETA_LABEL = 'beta'
 const UNRELEASED_LABEL = 'unreleased'
-const UNRELEASED_TOOLTIP =
-  'This feature is not in a released version of Redpanda yet. It is documented here for the upcoming release.'
+// The badge macro supplies the default hover text for these labels, so the same
+// wording appears whether a badge comes from the registry or from a
+// badge::[label=beta] call in a page.
+const UNRELEASED_TOOLTIP = DEFAULT_TOOLTIPS.unreleased
 
 // Release status of a feature, which decides where it may be referenced.
 //
@@ -97,9 +100,12 @@ const VALID_STATUSES = [STATUS_GA, STATUS_BETA, STATUS_UNRELEASED]
  * The release status of a registry entry.
  *
  * `beta: true` predates the status field and still means beta, so old entries
- * keep working. An explicit status wins. An unrecognized status is reported
- * rather than quietly treated as shipped, which is the failure mode that lets a
- * typo publish an unreleased feature.
+ * keep working. An explicit status wins. An unrecognized status is reported AND
+ * treated as unreleased: a typo must not be the thing that publishes an
+ * unreleased feature. The two failure directions are not symmetric -- gating a
+ * shipped feature shows a writer a warning and an unstyled mention they will
+ * notice, while publishing an unreleased one promises readers a feature they
+ * cannot get, and nothing on the page looks wrong.
  *
  * @param {object} entry - Registry entry.
  * @param {object} [report] - {mode, filePath} to report an invalid status.
@@ -107,14 +113,22 @@ const VALID_STATUSES = [STATUS_GA, STATUS_BETA, STATUS_UNRELEASED]
  */
 function entryStatus (entry, report) {
   if (!entry) return STATUS_GA
+  // Any present key goes through validation, including a blank value. An absent
+  // key means no status was intended, so GA is the right default; `status:` with
+  // nothing after it means the writer meant to say something and did not, which
+  // is the same mistake as a typo and must fail the same way. Treating blank as
+  // absent reopened the hole this function exists to close: a forgotten value
+  // published an unreleased feature with no warning at all.
   if (entry.status !== undefined) {
-    const status = String(entry.status).trim().toLowerCase()
+    const raw = entry.status === null ? '' : String(entry.status).trim()
+    const status = raw.toLowerCase()
     if (VALID_STATUSES.includes(status)) return status
     if (report && report.mode !== 'off') {
       const where = report.filePath ? ` in ${report.filePath}` : ''
+      const what = raw === '' ? 'an empty status' : `status '${entry.status}'`
       const message =
-        `enterprise:${entry.name}[]${where}: registry status '${entry.status}' is not one of ${VALID_STATUSES.join(', ')}, so the feature is treated as released. ` +
-        'Fix the status in enterprise-features.yml.'
+        `enterprise:${entry.name}[]${where}: registry has ${what}, which is not one of ${VALID_STATUSES.join(', ')}, so the feature is treated as unreleased and is left unpublished on released pages. ` +
+        'Fix the status in enterprise-features.yml, or remove the key entirely if the feature has shipped.'
       // Honour error mode like every other registry diagnostic. A typo here is
       // exactly what publishes an unreleased feature, so the strictest setting
       // has to stop it.
@@ -124,7 +138,7 @@ function entryStatus (entry, report) {
       if (report.contentCatalog) warnOnce(report.contentCatalog, `status:${entry.name}`, message)
       else console.warn(chalk.yellow(message))
     }
-    return STATUS_GA
+    return STATUS_UNRELEASED
   }
   return entry.beta === true ? STATUS_BETA : STATUS_GA
 }
@@ -239,7 +253,14 @@ let warnedNoRegistry = false
  * @returns {{features: object[], lookup: Map<string, object>}}
  */
 function parseRegistry (source, origin = REGISTRY_FILENAME) {
-  const data = yaml.load(source)
+  let data
+  try {
+    data = yaml.load(source)
+  } catch (error) {
+    // Every other throw below names the file, so this one does too: the caller
+    // then reports whatever it catches verbatim, and the path appears once.
+    throw new Error(`Enterprise features registry ${origin} is not valid YAML (${error.message}).`)
+  }
   if (!data || !Array.isArray(data.features)) {
     throw new Error(`Enterprise features registry ${origin} has no 'features' list.`)
   }
@@ -287,8 +308,17 @@ function loadRegistry (config) {
       // Caching the failure also stops the error being re-raised per macro call
       // and attributed to whichever page happened to convert first.
       registry = null
+      // Remember that the file was found and unreadable, so the caller does not
+      // then also report it missing. Saying "not found" about a file we just
+      // read and failed to parse sends the writer looking for the wrong problem.
+      contentCatalog[$enterpriseRegistryUnreadable] = true
+      // Report the error as thrown. It already names the file and says exactly
+      // what is wrong -- invalid YAML, a missing features list, an entry with no
+      // name, an unknown scope, or a duplicate name or alias. Wrapping it in
+      // "could not be read" was inaccurate for all but the first (the file read
+      // fine; its contents are invalid) and printed the path twice.
       warnOnce(contentCatalog, 'badregistry',
-        `Enterprise features registry ${registryFile.path} could not be read (${error.message}); enterprise: targets are not validated.`)
+        `${error.message} No enterprise: target is validated, no feature is gated by release status, and the licensing tables are empty until this is fixed.`)
     }
   }
   // Cache null too, so a missing registry is only searched for once per build.
@@ -297,6 +327,8 @@ function loadRegistry (config) {
 }
 
 function warnNoRegistry (contentCatalog) {
+  // Already reported as unreadable: one problem, one diagnostic.
+  if (contentCatalog && contentCatalog[$enterpriseRegistryUnreadable]) return
   const message = "Enterprise features registry (enterprise-features.yml in the 'shared' component) not found; enterprise: targets are not validated."
   // Deduplicate per build, not per process: Antora's watch mode reuses one
   // process across builds, and a module-level guard reported this only on a
@@ -377,7 +409,16 @@ function resolveTooltipAttribute (raw) {
 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;')
+  // All four, matching badge.js. Escaping only the quote kept the attribute
+  // intact but let < and > through from a registry tooltip field, which any
+  // consumer that re-parses the page then reads as markup -- the docs UI
+  // promotes this attribute into a tooltip, the Markdown converter and the
+  // search indexer both re-read it.
+  const escapedTooltip = tooltipText
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
   const tooltipHtml = tooltipAttr ? ` ${tooltipAttr}="${escapedTooltip}"` : ''
   let inner = display
   if (links) {
@@ -408,7 +449,15 @@ function buildFeatureTable (features, scope, opts = {}) {
   const report = opts.report
   const rows = features
     .filter((feature) => feature.scope === scope)
-    .filter((feature) => includeUnreleased || entryStatus(feature, report) !== STATUS_UNRELEASED)
+    // Evaluate the status first: `includeUnreleased || entryStatus(...)` skipped
+    // the call entirely on a prerelease page, so a typo'd status went unreported
+    // on the beta branch -- the one branch where unreleased features are
+    // actually authored and the table renders them -- and enterprise-validate=error
+    // did not fail there either.
+    .filter((feature) => {
+      const status = entryStatus(feature, report)
+      return includeUnreleased || status !== STATUS_UNRELEASED
+    })
     .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

package/macros/prop.js

@@ -6,7 +6,7 @@
  *
  *   prop:cloud_storage_enabled[]
  *   prop:iceberg_enabled[link=true]
- *   prop:retention_ms[link=true,page=properties/topic-properties]
+ *   prop:retention.ms[link=true,page=properties/topic-properties]
  *   prop:write_caching_default[text=write caching]
  *
  * The property renders as a marked <code> element that the docs UI decorates
@@ -98,7 +98,10 @@ const SURFACE_CLOUD = 'cloud'
 const PROPERTIES_JSON_RX = /^redpanda-properties-(v\d+\.\d+\.\d+(?:-[\w.]+)?)\.json$/
 
 const $propertyPageIndex = Symbol('$propertyPageIndex')
-const HEADING_RX = /^=+\s+(\S+)\s*$/
+// Two or more '=': a level-0 heading is the page title, which generates no
+// anchor, so treating it as a property heading produced a link and a tooltip
+// URL pointing at a fragment that does not exist on the page.
+const HEADING_RX = /^={2,}\s+(\S+)\s*$/
 const TAG_MARKER_RX = /^\/\/\s*(tag|end)::([\w-]+)\[\]\s*$/
 const INCLUDE_RX = /^include::([^[]+)\[([^\]]*)\]/
 // A reference page declaring the property collection it publishes.
@@ -314,7 +317,14 @@ function buildPageIndex (contentCatalog, component, properties, version) {
       if (!include) continue
       const partialRef = parsePartialTarget(include[1].trim(), page.src)
       if (!partialRef) continue
-      const tagsMatch = include[2].match(/tags?=([^,\]]+)/)
+      // Match a quoted value first. An unquoted value ends at the next comma
+      // because the attrlist is comma-separated -- but a quoted one may contain
+      // commas, and that is AsciiDoc's documented way to write a comma-separated
+      // tag list. Capturing up to the first comma regardless truncated
+      // tags="!deprecated,!exclude-from-docs" to '"!deprecated', which matches
+      // nothing, so the page indexed no properties and every link on it silently
+      // disappeared. Asciidoctor honours the quoted form, so the index has to.
+      const tagsMatch = include[2].match(/tags?=("[^"]*"|'[^']*'|[^,\]]*)/)
       const expression = tagsMatch && tagsMatch[1]
       const partials = contentCatalog.findBy({ component: partialRef.component, module: partialRef.module, family: 'partial' }) || []
       const matching = partials.filter((candidate) => candidate.src.relative === partialRef.relative)
@@ -364,6 +374,13 @@ function propertyAnchor (name) {
 // config.node, and every other cluster property maps to config.cluster --
 // the path the docs recommend for all cluster properties.
 function helmValuesPath (name, scope) {
+  // Topic properties are not set in values.yaml at all -- they are set per topic
+  // through the Kafka API, rpk, or a Topic resource -- so there is no Helm path
+  // to show. Returning config.cluster.<name> for them produced a confident,
+  // copy-pasteable key that does not exist, which is the exact failure the
+  // config_ref macro's blanket prefixing had. Undefined means "no Helm path",
+  // and the caller falls back to the plain property name.
+  if (scope === 'topic') return undefined
   if (name.startsWith('cloud_storage_')) return `storage.tiered.config.${name}`
   if (scope === 'broker') return `config.node.${name}`
   return `config.cluster.${name}`
@@ -523,7 +540,7 @@ function loadProperties (config) {
  * property-page-index extension can warm the caches before conversion.
  */
 function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
-  const cacheKey = `${pageComponent}@${pageVersion}` || '$any'
+  const cacheKey = `${pageComponent}@${pageVersion}`
   const cache = contentCatalog[$propertyRegistry] || (contentCatalog[$propertyRegistry] = {})
   if (cache[cacheKey] !== undefined) return cache[cacheKey] || undefined
 
@@ -531,6 +548,12 @@ function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
   const own = datasets.filter((d) => d.component === pageComponent)
   let pick
   let surface
+  // The candidates the corrupt-file fallback may fall back TO. It has to be the
+  // same filtered set `pick` was chosen from, not everything the component
+  // publishes: falling back across release series would validate a 25.3 page
+  // against 25.2 data, which is exactly the borrowing this function refuses to
+  // do on the primary path.
+  let pool
 
   // Cloud is decided first, and deliberately outranks the component's own
   // attachments. The property extractor writes
@@ -546,6 +569,7 @@ function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
     // version is not a Redpanda release candidate.
     const lenders = datasets.filter((d) => d.component === 'streaming' || d.component === 'ROOT')
     const released = lenders.filter((d) => !isPrerelease(d.tag))
+    pool = released
     pick =
       newestDataset(released.filter((d) => d.component === 'streaming')) ||
       newestDataset(released.filter((d) => d.component === 'ROOT'))
@@ -567,6 +591,7 @@ function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
     const series = releaseSeries(pageVersion)
     if (series) {
       const inSeries = own.filter((d) => releaseSeries(d.tag) === series)
+      pool = inSeries
       pick = newestDataset(inSeries.filter((d) => d.version === pageVersion)) || newestDataset(inSeries)
       if (!pick) {
         // Record the gap rather than reporting it here: this also runs from the
@@ -585,6 +610,7 @@ function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
         return undefined
       }
     } else {
+      pool = own
       pick = newestDataset(own.filter((d) => d.version === pageVersion)) || newestDataset(own)
     }
   }
@@ -593,12 +619,26 @@ function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
   // and must not mask a good file: try candidates newest-first and use the
   // first one that actually carries properties, reporting each one skipped.
   let registry = null
-  for (const candidate of orderedCandidates(pick, own, datasets, surface)) {
+  const candidates = orderedCandidates(pick, pool)
+  for (const candidate of candidates) {
     const properties = readProperties(candidate, contentCatalog)
     if (!properties) continue
     registry = { tag: candidate.tag, properties, component: candidate.component, version: candidate.version, surface }
     break
   }
+  if (!registry && candidates.length) {
+    // Every candidate was unusable. Record that, because the caller's fallback
+    // diagnostic says no attachment exists anywhere -- which contradicts the
+    // per-file warning readProperties just emitted and sends the writer looking
+    // for a file that is sitting right there.
+    const gaps = contentCatalog[$propertySeriesGap] || (contentCatalog[$propertySeriesGap] = {})
+    gaps[cacheKey] = {
+      kind: 'unusable',
+      component: pageComponent,
+      version: pageVersion,
+      have: [...new Set(candidates.map((d) => d.tag))].sort(compareTags),
+    }
+  }
   // Cache null too, so a missing dataset is only searched for once per build.
   cache[cacheKey] = registry
   return registry || undefined
@@ -609,12 +649,9 @@ function loadPropertiesFor (contentCatalog, pageComponent, pageVersion) {
  * descending release order, so an unusable file falls through to the next best
  * rather than voiding the component's data entirely.
  */
-function orderedCandidates (pick, own, datasets, surface) {
+function orderedCandidates (pick, pool) {
   if (!pick) return []
-  const pool = surface === SURFACE_CLOUD
-    ? datasets.filter((d) => (d.component === 'streaming' || d.component === 'ROOT') && !isPrerelease(d.tag))
-    : own
-  const rest = pool
+  const rest = (pool || [])
     .filter((d) => d !== pick)
     .sort((a, b) => compareTags(b.tag, a.tag) || stableKey(a).localeCompare(stableKey(b)))
   return [pick, ...rest]
@@ -683,6 +720,12 @@ function warnSeriesMissing (contentCatalog, pageComponent, pageVersion) {
   const gap = gaps && gaps[`${pageComponent}@${pageVersion}`]
   if (!gap) return false
   const have = gap.have.join(', ')
+  if (gap.kind === 'unusable') {
+    warnOnce(contentCatalog, `unusable:${gap.component}@${gap.version}`,
+      `prop macro: every property attachment for ${gap.component}@${gap.version} is unusable (${have}); see the per-file warning above for why. ` +
+      'prop: targets are therefore not validated and their tooltips carry no data. Regenerate the file with \'npx doc-tools generate property-docs\' rather than treating this as missing data.')
+    return true
+  }
   if (gap.kind === 'cloud-prerelease-only') {
     warnOnce(contentCatalog, `cloudpre:${gap.component}@${gap.version}`,
       `prop macro: ${gap.component} found only prerelease property data (${have}). Cloud runs released Redpanda, so it uses GA property data and will not validate against a release candidate. ` +
@@ -788,7 +831,7 @@ function reportUnpublishedProperty ({ name, registry, mode, filePath }) {
  * @returns {string}
  */
 function buildPropContent ({ name, text, link, page, scope, role, helmPath = false, docUrl, plain = false }) {
-  const display = text || (helmPath ? helmValuesPath(name, scope) : name)
+  const display = text || (helmPath && helmValuesPath(name, scope)) || name
   if (plain) return `<code>${display}</code>`
   const inner = link && page
     ? `xref:reference:${page}.adoc#${propertyAnchor(name)}[${display}]`
@@ -915,7 +958,11 @@ function propInlineMacro (config) {
  * hardcoded storage.tiered.config prefixing).
  */
 function helmPathRequested (attributes, document) {
-  return attributes['helm-path'] === 'auto' && document.getAttribute('env-kubernetes') !== undefined
+  // isAttributeSet, not a bare !== undefined: Antora yields the string 'false'
+  // for `env-kubernetes: false` in antora.yml, and a bare presence check read
+  // that as "Kubernetes page", so a Linux page in a component that explicitly
+  // turned the attribute off still told readers to set a values.yaml key.
+  return attributes['helm-path'] === 'auto' && isAttributeSet(document.getAttribute('env-kubernetes'))
 }
 
 function register (registry, config = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.12.0",
+  "version": "5.12.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/property-extractor/generate-handlebars-docs.js

@@ -104,6 +104,103 @@ function registerPartials() {
   }
 }
 
+/**
+ * Rewrite property anchors across every description and related-topics entry so
+ * they match the heading IDs Asciidoctor will actually emit.
+ *
+ * Runs once over the whole property map before rendering, because a property's
+ * description routinely links to a sibling property and the anchor shapes differ
+ * by where the text came from. Reports what it corrected: a steady stream of
+ * rewrites is a signal to fix the upstream doc string, not to lean on this pass.
+ *
+ * @param {Object<string, Object>} properties - Property map, mutated in place.
+ * @returns {number} Number of anchors rewritten.
+ */
+function normalizeAnchorsInProperties(properties) {
+  const seen = new Map();
+  let total = 0;
+
+  let xrefTotal = 0;
+  const fix = (value, scope) => {
+    const { text, rewrites } = helpers.normalizePropertyAnchors(value, properties, scope);
+    for (const r of rewrites) {
+      total += 1;
+      seen.set(r.from, r.to);
+    }
+    const canonical = helpers.canonicalizePropertyXrefs(text);
+    xrefTotal += canonical.rewrites;
+    return canonical.text;
+  };
+
+  Object.values(properties).forEach((prop) => {
+    if (!prop || typeof prop !== 'object') return;
+    const scope = prop.config_scope;
+    if (typeof prop.description === 'string') prop.description = fix(prop.description, scope);
+    if (typeof prop.acceptable_values === 'string') prop.acceptable_values = fix(prop.acceptable_values, scope);
+    if (Array.isArray(prop.related_topics)) {
+      // Canonicalizing collapses forms that differed only by prefix, which turns
+      // some entries into exact duplicates of each other. Drop the repeats.
+      const seenTopics = new Set();
+      prop.related_topics = prop.related_topics
+        .map((t) => (typeof t === 'string' ? fix(t, scope) : t))
+        .filter((t) => {
+          if (typeof t !== 'string') return true;
+          const key = t.trim();
+          if (seenTopics.has(key)) return false;
+          seenTopics.add(key);
+          return true;
+        });
+    }
+  });
+
+  if (total > 0) {
+    console.log(`Fixed ${total} property anchor(s) that would have rendered as dead links:`);
+    for (const [from, to] of seen) console.log(`   <<${from}>> -> <<${to}>>`);
+  }
+  if (xrefTotal > 0) {
+    console.log(`Canonicalized ${xrefTotal} property-page xref(s) to reference:properties/…`);
+  }
+  return total;
+}
+
+/**
+ * Record whether a topic property's corresponding cluster property is one a Cloud
+ * customer can actually reach.
+ *
+ * Cloud publishes a subset of cluster properties, so linking a topic property to
+ * its cluster counterpart unconditionally sends Cloud readers to an anchor that
+ * does not exist on their reference page. `cloud_supported` on the cluster
+ * property is the authority here: it is derived from the install pack's
+ * customer_managed_configs and readonly_cluster_config, so true means the Cloud
+ * page publishes it.
+ *
+ * Note what this flag does NOT say. False means the control plane does not expose
+ * the property to customers; it does not distinguish "Redpanda manages the value"
+ * from "the property does not apply to Cloud at all". So the template drops the
+ * link and keeps the name, and asserts nothing about who sets it.
+ *
+ * Both the primary and the alternate mapping are resolved, because a row that
+ * links to two cluster properties needs both to be reachable before it is worth
+ * linking either.
+ *
+ * @param {Object} prop - Topic property to annotate in place.
+ * @param {Object<string, Object>} properties - Full property map, used to look up counterparts.
+ */
+function annotateCorrespondingClusterSupport(prop, properties) {
+  const isSupported = (name) => {
+    if (!name) return false;
+    const target = properties[name];
+    return Boolean(target && target.cloud_supported);
+  };
+
+  const primary = isSupported(prop.corresponding_cluster_property);
+  prop.corresponding_cluster_property_cloud_supported = primary;
+  prop.alternate_cluster_property_cloud_supported = isSupported(prop.alternate_cluster_property);
+  prop.cluster_property_mapping_cloud_supported = prop.alternate_cluster_property
+    ? primary && prop.alternate_cluster_property_cloud_supported
+    : primary;
+}
+
 /**
  * Generate AsciiDoc partial files grouping input properties by scope (cluster, topic, broker, object-storage).
  *
@@ -120,6 +217,8 @@ function registerPartials() {
 function generatePropertyPartials(properties, partialsDir, onRender) {
   console.log(`📝 Generating consolidated property partials in ${partialsDir}…`);
 
+  normalizeAnchorsInProperties(properties);
+
   const propertyTemplate = handlebars.compile(
     fs.readFileSync(getTemplatePath(path.join(__dirname, 'templates', 'property.hbs'), 'TEMPLATE_PROPERTY'), 'utf8')
   );
@@ -151,6 +250,7 @@ function generatePropertyPartials(properties, partialsDir, onRender) {
 
     switch (prop.config_scope) {
       case 'topic':
+        annotateCorrespondingClusterSupport(prop, properties);
         propertyGroups.topic.push(prop);
         break;
       case 'broker':

package/tools/property-extractor/helpers/anchorName.js

@@ -1,5 +1,18 @@
+// Builds the anchor for a property's generated section heading.
+//
+// The headings are plain AsciiDoc (`=== cleanup.policy`), so Asciidoctor derives
+// their IDs itself: lowercase, every run of characters outside [a-z0-9_] replaced
+// with the id separator, which Antora sets to `-`. Underscores are word
+// characters and survive, so `redpanda.cloud_topic.enabled` becomes
+// `redpanda-cloud_topic-enabled`.
+//
+// Reproduce that here rather than inventing a separate scheme: anything else
+// renders as a link to an anchor that does not exist on the page.
 module.exports = function anchorName(name) {
-  const anchor = String(name).replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+  const anchor = String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, '-')
+    .replace(/^-+|-+$/g, '');
   if (!anchor) {
     throw new Error(`Invalid property name for anchor generation: "${name}"`);
   }

package/tools/property-extractor/helpers/canonicalizePropertyXrefs.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// The reference pages these xrefs target.
+const PROPERTY_PAGES = [
+  'cluster-properties',
+  'object-storage-properties',
+  'topic-properties',
+  'broker-properties',
+];
+
+// Every prefix seen in the wild for the same target:
+//   xref:cluster-properties.adoc#x            bare filename
+//   xref:./cluster-properties.adoc#x          relative to the current directory
+//   xref:reference:cluster-properties.adoc#x  legacy, when the pages sat at the module root
+//   xref:reference:properties/...#x           canonical
+const PREFIXES = '(?:\\./|reference:properties/|reference:)?';
+const PATTERN = new RegExp(
+  `xref:${PREFIXES}(${PROPERTY_PAGES.join('|')})\\.adoc(?=[#\\[])`,
+  'g'
+);
+
+/**
+ * Rewrite every reference to a property reference page to one canonical resource ID.
+ *
+ * The bare and `reference:`-prefixed forms both resolve to the module root, where
+ * these pages no longer live. Self-managed papers over that with a
+ * `reference:cluster-properties.adoc` page alias, so the broken form renders as a
+ * working link there and as an unresolved xref in cloud-docs, which has no such
+ * alias. The `./` form works but depends on the including page sitting in
+ * `reference/properties/`, which is a constraint on every page that includes a
+ * partial rather than a property of the partial.
+ *
+ * The fully qualified module-and-path form has neither problem: it resolves
+ * inside whichever component includes the partial, from any directory.
+ *
+ * @param {string} text - AsciiDoc source that may contain property-page xrefs.
+ * @returns {{text: string, rewrites: number}}
+ */
+function canonicalizePropertyXrefs(text) {
+  if (typeof text !== 'string' || !text.includes('xref:')) {
+    return { text, rewrites: 0 };
+  }
+  let rewrites = 0;
+  const out = text.replace(PATTERN, (match, page) => {
+    const canonical = `xref:reference:properties/${page}.adoc`;
+    if (match === canonical) return match;
+    rewrites += 1;
+    return canonical;
+  });
+  return { text: out, rewrites };
+}
+
+module.exports = canonicalizePropertyXrefs;
+module.exports.PROPERTY_PAGES = PROPERTY_PAGES;

package/tools/property-extractor/helpers/index.js

@@ -14,6 +14,8 @@ module.exports = {
   renderPropertyExample: require('./renderPropertyExample.js'),
   formatUnits: require('./formatUnits.js'),
   anchorName: require('./anchorName.js'),
+  normalizePropertyAnchors: require('./normalizePropertyAnchors.js'),
+  canonicalizePropertyXrefs: require('./canonicalizePropertyXrefs.js'),
   parseRelatedTopic: require('./parseRelatedTopic.js'),
   allTopicsConditional: require('./allTopicsConditional.js'),
   capitalize: require('./capitalize.js'),

package/tools/property-extractor/helpers/normalizePropertyAnchors.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const anchorName = require('./anchorName.js');
+
+// Strip every separator so `redpanda.storage.mode.impl`, `redpanda-storage-mode-impl`
+// and `redpandastoragemodeimpl` all collapse to one key.
+function squash(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/**
+ * Repair intra-page anchors (`<<anchor,text>>`) that name a property but use the
+ * wrong ID shape.
+ *
+ * Descriptions come from three places -- Redpanda's own doc strings, the
+ * overrides file, and hand-edits -- and each has at some point written a
+ * property anchor by deleting the dots (`<<redpandastoragemodeimpl>>`) or by
+ * hyphenating only part of the name (`<<redpandastorage-mode>>`). Asciidoctor
+ * derives the real heading ID from the heading text, so those render as links to
+ * nothing. Rather than hand-correct each one and wait for the next author to
+ * reintroduce it, resolve any anchor that unambiguously names a known property
+ * back to that property's real anchor.
+ *
+ * Only rewrites when the anchor is not already correct and the match is
+ * unambiguous, so an anchor pointing at a genuine non-property section is left
+ * alone. Names from different scopes can collide once separators are gone --
+ * `retention.bytes` and `retention_bytes` both squash to `retentionbytes` -- so
+ * a collision is resolved in favour of the scope the referring property is in,
+ * which is where a cross-reference nearly always points, and refused outright if
+ * that still leaves two candidates.
+ *
+ * @param {string} text - AsciiDoc source that may contain `<<anchor,label>>` references.
+ * @param {Iterable<string>|Object<string, Object>} properties - Known property names, or the property map.
+ * @param {string} [scope] - config_scope of the property that owns this text.
+ * @returns {{text: string, rewrites: Array<{from: string, to: string}>}}
+ */
+function normalizePropertyAnchors(text, properties, scope) {
+  if (typeof text !== 'string' || !text.includes('<<')) {
+    return { text, rewrites: [] };
+  }
+
+  const isMap = properties && !Array.isArray(properties) && typeof properties === 'object'
+    && !(typeof properties[Symbol.iterator] === 'function');
+  const names = isMap ? Object.keys(properties) : Array.from(properties || []);
+  const scopeOf = (name) => (isMap && properties[name] ? properties[name].config_scope : undefined);
+
+  const bySquashed = new Map();
+  const validAnchors = new Set();
+  for (const name of names) {
+    if (typeof name !== 'string' || !name) continue;
+    let anchor;
+    try {
+      anchor = anchorName(name);
+    } catch {
+      continue;
+    }
+    validAnchors.add(anchor);
+    const key = squash(name);
+    const entry = bySquashed.get(key);
+    if (entry) entry.push({ anchor, scope: scopeOf(name) });
+    else bySquashed.set(key, [{ anchor, scope: scopeOf(name) }]);
+  }
+
+  const resolve = (key) => {
+    const candidates = bySquashed.get(key);
+    if (!candidates || candidates.length === 0) return null;
+    if (candidates.length === 1) return candidates[0].anchor;
+    const sameScope = scope ? candidates.filter((c) => c.scope === scope) : [];
+    return sameScope.length === 1 ? sameScope[0].anchor : null;
+  };
+
+  const rewrites = [];
+  const rewritten = text.replace(/<<([^<>,\]]+?)(,|>>)/g, (match, anchor, tail) => {
+    const trimmed = anchor.trim();
+    if (validAnchors.has(trimmed)) return match;
+    const target = resolve(squash(trimmed));
+    if (!target || target === trimmed) return match;
+    rewrites.push({ from: trimmed, to: target });
+    return `<<${target}${tail}`;
+  });
+
+  return { text: rewritten, rewrites };
+}
+
+module.exports = normalizePropertyAnchors;
+module.exports.squash = squash;

package/tools/property-extractor/templates/topic-property-mappings.hbs

@@ -4,12 +4,21 @@
 
 {{#each topicProperties}}
 | <<{{anchorName name}},`{{name}}`>>
-| {{#if alternate_cluster_property}}xref:./{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`] or xref:./{{alternate_cluster_property_doc_file}}#{{alternate_cluster_property}}[`{{alternate_cluster_property}}`]{{else}}xref:./{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]{{/if}}
+|
+ifdef::env-cloud[]
+{{#if cluster_property_mapping_cloud_supported}}
+{{#if alternate_cluster_property}}xref:reference:properties/{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`] or xref:reference:properties/{{alternate_cluster_property_doc_file}}#{{alternate_cluster_property}}[`{{alternate_cluster_property}}`]{{else}}xref:reference:properties/{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]{{/if}}
+{{else}}
+{{#if alternate_cluster_property}}`{{corresponding_cluster_property}}` or `{{alternate_cluster_property}}`{{else}}`{{corresponding_cluster_property}}`{{/if}}
+{{/if}}
+endif::[]
+ifndef::env-cloud[]
+{{#if alternate_cluster_property}}xref:reference:properties/{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`] or xref:reference:properties/{{alternate_cluster_property_doc_file}}#{{alternate_cluster_property}}[`{{alternate_cluster_property}}`]{{else}}xref:reference:properties/{{cluster_property_doc_file}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]{{/if}}
+endif::[]
 
 {{/each}}
 
 |===
 
-{{!-- Helper to generate anchor names --}}
-{{!-- Usage: anchorName propertyName --}}
-{{!-- Example: cleanup.policy -> cleanuppolicy --}}
+{{!-- Anchors come from the anchorName helper, which reproduces Asciidoctor's --}}
+{{!-- own auto-generated heading ID: cleanup.policy -> cleanup-policy. --}}

package/tools/property-extractor/templates/topic-property.hbs

@@ -77,7 +77,17 @@ endif::[]
 {{#if corresponding_cluster_property}}
 
 | Corresponding cluster property
-| xref:reference:cluster-properties.adoc#{{corresponding_cluster_property}}[{{corresponding_cluster_property}}]
+|
+ifdef::env-cloud[]
+{{#if corresponding_cluster_property_cloud_supported}}
+xref:reference:properties/{{#if cluster_property_doc_file}}{{cluster_property_doc_file}}{{else}}cluster-properties.adoc{{/if}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]
+{{else}}
+`{{corresponding_cluster_property}}`
+{{/if}}
+endif::[]
+ifndef::env-cloud[]
+xref:reference:properties/{{#if cluster_property_doc_file}}{{cluster_property_doc_file}}{{else}}cluster-properties.adoc{{/if}}#{{corresponding_cluster_property}}[`{{corresponding_cluster_property}}`]
+endif::[]
 {{/if}}
 {{#if (and minimum maximum)}}