@redpanda-data/docs-extensions-and-macros 5.17.0 → 5.22.1

package/bin/doc-tools.js

@@ -2475,6 +2475,88 @@ validation
     }
   })
 
+/**
+ * validate property-overrides
+ *
+ * @description
+ * Validates docs-data/property-overrides.json against its JSON Schema:
+ * unknown keys (a typo that would otherwise be silently dropped by the
+ * extractor), and the see_also shape (a plain string, or an object naming
+ * exactly one of cloud_only/self_hosted_only).
+ *
+ * @why
+ * property-overrides.json has no catch-all pass-through when an override
+ * targets an existing property — an unrecognized key like the typo
+ * `acceptable_values` (the generated-only field is `acceptable_values`, but
+ * the override key the extractor reads is `accepted_values`) is silently
+ * ignored rather than erroring. This check catches that class of mistake
+ * before generation, the same way `validate rpk-overrides` does for rpk.
+ *
+ * @example
+ * # Validate overrides with the default path
+ * npx doc-tools validate property-overrides
+ *
+ * # Validate a custom overrides file
+ * npx doc-tools validate property-overrides --overrides my-overrides.json
+ *
+ * # Strict mode - exit with error code on validation failures
+ * npx doc-tools validate property-overrides --strict
+ *
+ * @requirements
+ * - property-overrides.schema.json in docs-data/
+ */
+validation
+  .command('property-overrides')
+  .description('Validate property-overrides.json against its schema')
+  .option('--overrides <path>', 'Path to overrides JSON file', 'docs-data/property-overrides.json')
+  .option('--strict', 'Exit with error code on validation failures')
+  .action((options) => {
+    try {
+      const { loadAndValidateOverrides } = require('../tools/property-extractor/validate-overrides.js')
+      const repoRoot = findRepoRoot()
+      const overridesPath = path.resolve(repoRoot, options.overrides)
+
+      console.log(`Validating: ${overridesPath}`)
+      console.log('')
+
+      const { overrides, validation: result } = loadAndValidateOverrides(overridesPath)
+
+      if (!overrides) {
+        console.error('Error: Could not load overrides file')
+        process.exit(1)
+      }
+
+      console.log('='.repeat(60))
+      console.log('VALIDATION RESULTS')
+      console.log('='.repeat(60))
+
+      if (result.errors.length === 0 && result.warnings.length === 0) {
+        console.log('✓ No issues found')
+      } else {
+        console.log(result.format())
+      }
+
+      console.log('='.repeat(60))
+      console.log(`Errors: ${result.errors.length}`)
+      console.log(`Warnings: ${result.warnings.length}`)
+      console.log('='.repeat(60))
+
+      if (options.strict && !result.valid) {
+        console.log('\n✗ Validation failed (strict mode)')
+        process.exit(1)
+      } else if (result.valid) {
+        console.log('\n✓ Validation passed')
+        process.exit(0)
+      } else {
+        console.log('\n⚠ Validation completed with errors (use --strict to fail)')
+        process.exit(0)
+      }
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
 /**
  * lint-strings
  *

package/cli-utils/validation-result.js

@@ -0,0 +1,53 @@
+'use strict'
+
+/**
+ * Accumulates errors and warnings across a validation pass, so a set of
+ * independent checks (schema shape, cross-references, semantic rules) can
+ * each report findings and have them merged into one result the caller
+ * prints and exits on. Shared by every overrides validator in this repo —
+ * originally written for tools/rpk-docs/validate-overrides.js, extracted
+ * here once tools/property-extractor needed the identical accumulator.
+ */
+class ValidationResult {
+  constructor() {
+    this.valid = true
+    this.errors = []
+    this.warnings = []
+  }
+
+  addError(message, context = null) {
+    this.valid = false
+    this.errors.push({ message, context })
+  }
+
+  addWarning(message, context = null) {
+    this.warnings.push({ message, context })
+  }
+
+  merge(other) {
+    if (!other.valid) this.valid = false
+    this.errors.push(...other.errors)
+    this.warnings.push(...other.warnings)
+  }
+
+  format() {
+    const lines = []
+    if (this.errors.length > 0) {
+      lines.push('ERRORS:')
+      for (const err of this.errors) {
+        lines.push(`  ✗ ${err.message}`)
+        if (err.context) lines.push(`    at: ${err.context}`)
+      }
+    }
+    if (this.warnings.length > 0) {
+      lines.push('WARNINGS:')
+      for (const warn of this.warnings) {
+        lines.push(`  ⚠ ${warn.message}`)
+        if (warn.context) lines.push(`    at: ${warn.context}`)
+      }
+    }
+    return lines.join('\n')
+  }
+}
+
+module.exports = { ValidationResult }

package/extension-utils/llms-utils.js

@@ -71,10 +71,36 @@ function stripMarkdownMetadata(content) {
   return text.trim();
 }
 
+/**
+ * Return the subset of `components` that have at least one page in `pages` —
+ * i.e. the components that actually get a generated `<name>-full.txt` export.
+ *
+ * A `<name>-full.txt` file is only written for components that have pages, so
+ * advertising an export for a corpus-less landing/utility component (e.g.
+ * `data-platform`, `self-managed`, `search`) links the AI index to a 404.
+ * Filtering the advertised list through this helper keeps it in sync with the
+ * files that are actually produced. Input order is preserved.
+ *
+ * @param {Array<{name: string}>} components - All components from the content catalog
+ * @param {Array<{src?: {component?: string}}>} pages - Pages that will be exported
+ * @returns {Array<{name: string}>} Components that have at least one page
+ */
+function componentsWithExports(components, pages) {
+  const componentNames = new Set(
+    (pages || [])
+      .map((page) => page && page.src && page.src.component)
+      .filter(Boolean)
+  );
+  return (components || []).filter((component) =>
+    componentNames.has(component.name)
+  );
+}
+
 module.exports = {
   LLMS_DIRECTIVE_BASE,
   LLMS_DIRECTIVE_REGEX,
   SOURCE_COMMENT_REGEX,
   formatLlmsDirective,
   stripMarkdownMetadata,
+  componentsWithExports,
 };

package/extensions/convert-llms-to-txt.js

@@ -3,7 +3,7 @@
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
 
 const { toMarkdownUrl } = require('../extension-utils/url-utils');
-const { stripMarkdownMetadata } = require('../extension-utils/llms-utils');
+const { stripMarkdownMetadata, componentsWithExports } = require('../extension-utils/llms-utils');
 
 /**
  * Extracts markdown from llms.adoc page and generates AI-friendly documentation exports.
@@ -167,7 +167,11 @@ module.exports.register = function () {
     fullContent += `- **${siteUrl}/llms.txt**: Curated overview following the llms.txt standard - start here for a quick introduction\n`;
     fullContent += `- **${siteUrl}/llms-full.txt**: Complete documentation export (this file) - comprehensive reference with all pages\n`;
     fullContent += `- **Component-specific exports**: Focused documentation for individual products:\n`;
-    components.forEach(component => {
+    // Only advertise exports for components that actually have pages — a
+    // `<name>-full.txt` is generated per component below, so listing corpus-less
+    // landing/utility components (e.g. data-platform, self-managed, search) would
+    // point the AI index at a 404.
+    componentsWithExports(components, pages).forEach(component => {
       fullContent += `  - \`${siteUrl}/${component.name}-full.txt\`: ${component.title}\n`;
     });
     fullContent += `- **Individual markdown pages**: Each HTML page has a corresponding .md file (e.g., \`/docs/page.html\` → \`/docs/page.md\`)\n\n`;

package/macros/REFERENCE.adoc

@@ -220,16 +220,17 @@ 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:cloud_storage_enabled[link=true,page=cloud:reference:properties/cluster-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-availability>> 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`). Discovered 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.
+Optional reference-page override, without `.adoc`. Overrides discovery entirely, and is never build-verified either way, so it may name any page that documents the property. A bare name (`properties/object-storage-properties`) stays module-relative within `reference` in the current component; qualify it with a module (`guides:cloud/object-storage`) or a component and module (`cloud:reference:properties/cluster-properties`) to point elsewhere.
 
 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 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.

package/macros/prop.js

@@ -7,6 +7,7 @@
  *   prop:cloud_storage_enabled[]
  *   prop:iceberg_enabled[link=true]
  *   prop:retention.ms[link=true,page=properties/topic-properties]
+ *   prop:cloud_storage_enabled[link=true,page=cloud:reference:properties/cluster-properties]
  *   prop:write_caching_default[text=write caching]
  *
  * The property renders as a marked <code> element that the docs UI decorates
@@ -54,11 +55,17 @@
  * a page in this component actually documents it. The page is discovered by
  * indexing which reference-module page documents each property, scanning
  * property headings in the partials each page includes and respecting include
- * tag filters such as tags=redpanda-cloud. Links are therefore
+ * tag filters such as tags=redpanda-cloud. Discovered links are therefore
  * component-relative and stay correct if properties are split across
- * different pages later. Nothing is ever linked across components, and no
- * page target is guessed from a property's scope: a link the build cannot
- * verify would be a broken link. Use page= to set the target explicitly.
+ * different pages later: nothing is ever discovered across components, and no
+ * page target is guessed from a property's scope, because a link the build
+ * cannot verify would be a broken link.
+ *
+ * Use page= to set the target explicitly instead of discovering it -- an
+ * override the build does not verify either way, so it may name any page that
+ * documents the property, in this component or another: a bare name
+ * (properties/topic-properties) stays module-relative within reference here,
+ * while module:page or component:module:page points anywhere else.
  *
  * With helm-path=auto, pages rendered with the env-kubernetes attribute
  * display the property as its Helm values path (storage.tiered.config.*
@@ -814,6 +821,23 @@ function reportUnpublishedProperty ({ name, registry, mode, filePath }) {
   ))
 }
 
+/**
+ * Resolve a page= value into the resource ID prefix an xref needs, before the
+ * trailing .adoc. A bare name (no colon) is module-relative within reference
+ * in the page's own component, matching every page= value published today.
+ * Qualifying it with a module (module:page) or a component and module
+ * (component:module:page) points the link anywhere else the property is
+ * documented: page= is never build-verified (buildPageIndex only runs when
+ * page= is absent), so restricting its shape bought no safety, only
+ * inflexibility.
+ *
+ * @param {string} page
+ * @returns {string}
+ */
+function resolvePageTarget (page) {
+  return page.includes(':') ? page : `reference:${page}`
+}
+
 /**
  * Build the AsciiDoc content emitted for one macro instance. Exported for
  * unit testing.
@@ -823,7 +847,10 @@ function reportUnpublishedProperty ({ name, registry, mode, filePath }) {
  * @param {string} [opts.text] - Display text override.
  * @param {boolean} [opts.link] - Whether to link to the reference page. Ignored
  *   without a page: the macro never guesses a target.
- * @param {string} [opts.page] - Reference page (module-relative, no .adoc).
+ * @param {string} [opts.page] - Reference page. A bare name (no colon) is
+ *   module-relative within reference in the current component; qualify it
+ *   with a module (module:page) or a component and module
+ *   (component:module:page) to point elsewhere. No .adoc.
  * @param {string} [opts.scope] - config_scope, used only for the Helm path.
  * @param {string} opts.role - CSS class for the code element.
  * @param {boolean} [opts.plain] - Render unmarked code (no tooltip, no link)
@@ -834,7 +861,7 @@ function buildPropContent ({ name, text, link, page, scope, role, helmPath = fal
   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}]`
+    ? `xref:${resolvePageTarget(page)}.adoc#${propertyAnchor(name)}[${display}]`
     : display
   // Escape every interpolated attribute value. role comes from a site
   // attribute, docUrl from a page's published URL, and name from a dataset
@@ -980,6 +1007,7 @@ function register (registry, config = {}) {
 
 module.exports.register = register
 module.exports.buildPropContent = buildPropContent
+module.exports.resolvePageTarget = resolvePageTarget
 module.exports.propertyAnchor = propertyAnchor
 module.exports.helmValuesPath = helmValuesPath
 module.exports.loadPropertiesFor = loadPropertiesFor

package/package.json

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

package/tools/property-extractor/README.adoc

@@ -142,8 +142,12 @@ Create a `property-overrides.json` file to customize extracted documentation:
       "description": "Network address and port for Kafka API clients to connect to Redpanda brokers.",
       "example": ".Example\n[,yaml]\n----\nredpanda:\n  kafka_api:\n    - name: internal\n      address: 0.0.0.0\n      port: 9092\n    - name: external\n      address: redpanda.example.com\n      port: 19092\n----",
       "version": "v21.4.1",
-      "related_topics": [
-        "xref:manage:kubernetes/networking/k-networking-and-connectivity.adoc[]"
+      "see_also": [
+        "xref:manage:kubernetes/networking/k-networking-and-connectivity.adoc[]",
+        {
+          "content": "xref:manage:cluster-maintenance/config-cluster.adoc[]",
+          "cloud_only": true
+        }
       ]
     }
   }
@@ -156,7 +160,17 @@ Create a `property-overrides.json` file to customize extracted documentation:
 * `example` - Add usage example in AsciiDoc format
 * `example_file` - Load example from external file
 * `version` - Document when property was introduced
-* `related_topics` - Array of AsciiDoc xrefs to related content
+* `see_also` - Array of related links. Each item is either a plain string (shown in every build) or an object `{content, cloud_only}` / `{content, self_hosted_only}` (shown only in that build, wrapped with `ifdef::env-cloud[]`/`ifndef::env-cloud[]` at generation time). Setting both `cloud_only` and `self_hosted_only` on the same item is rejected by the schema — it would wrap the item in both directives at once, so it renders in neither build.
+* `related_topics` - Deprecated predecessor to `see_also`. An array of plain strings, optionally prefixed `cloud-only:` / `self-managed-only:` for the same conditional behavior — that prefix is free text with no validation, which is why `see_also` replaced it. Existing `related_topics` entries keep working; new entries should use `see_also`.
+
+Validate an overrides file against its schema (`docs-data/property-overrides.schema.json`) before generating docs:
+
+[,bash]
+----
+npx doc-tools validate property-overrides --overrides docs-data/property-overrides.json
+----
+
+This catches malformed `see_also` items and unrecognized override keys — including a typo that would otherwise be silently dropped, since applying an override to an *existing* property has no catch-all pass-through (only overrides that create a new property from scratch do).
 
 === Understanding property changes
 

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

@@ -16,8 +16,7 @@ module.exports = {
   anchorName: require('./anchorName.js'),
   normalizePropertyAnchors: require('./normalizePropertyAnchors.js'),
   canonicalizePropertyXrefs: require('./canonicalizePropertyXrefs.js'),
-  parseRelatedTopic: require('./parseRelatedTopic.js'),
-  allTopicsConditional: require('./allTopicsConditional.js'),
+  seeAlsoView: require('./seeAlsoView.js'),
   capitalize: require('./capitalize.js'),
   length: require('./length.js'),
 };

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

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Normalizes a property's related-topics data into one shape for the
+ * templates to render, regardless of which field or convention the override
+ * author used:
+ *
+ *   - see_also (current): array of items, each either a plain string (shown
+ *     everywhere) or {content, cloud_only, self_hosted_only} (shown only in
+ *     the named build). Schema-validated — see docs-data/property-overrides.schema.json.
+ *   - related_topics (deprecated, still read for back-compat with existing
+ *     override files): array of strings, optionally prefixed with
+ *     'cloud-only:' / 'self-managed-only:' to get the same conditional
+ *     behaviour. That prefix was free text with no validation; see_also
+ *     replaces it with data a schema can check.
+ *
+ * @param {object} property - A property record, as extracted or overridden.
+ * @returns {Array<{content: string, cloudOnly: boolean, selfHostedOnly: boolean}>}
+ */
+function normalizeSeeAlso(property) {
+  if (!property) return [];
+  const rawItems = Array.isArray(property.see_also)
+    ? property.see_also
+    : Array.isArray(property.related_topics)
+      ? property.related_topics
+      : [];
+
+  return rawItems
+    .map((item) => {
+      if (typeof item === 'string') {
+        const trimmed = item.trim();
+        if (trimmed.startsWith('cloud-only:')) {
+          return { content: trimmed.slice('cloud-only:'.length).trim(), cloudOnly: true, selfHostedOnly: false };
+        }
+        if (trimmed.startsWith('self-managed-only:')) {
+          return { content: trimmed.slice('self-managed-only:'.length).trim(), cloudOnly: false, selfHostedOnly: true };
+        }
+        return { content: trimmed, cloudOnly: false, selfHostedOnly: false };
+      }
+      if (item && typeof item === 'object' && typeof item.content === 'string') {
+        return {
+          content: item.content.trim(),
+          cloudOnly: item.cloud_only === true,
+          selfHostedOnly: item.self_hosted_only === true,
+        };
+      }
+      return null;
+    })
+    .filter((item) => item && item.content);
+}
+
+/**
+ * Builds the single view object property.hbs/topic-property.hbs render the
+ * "Related topics" row from: the normalized item list, plus which env-cloud
+ * branch (if any) every item shares, so the row's own header can be wrapped
+ * once instead of duplicated per item.
+ *
+ * sectionType is 'cloud' only when every item is cloud-only, 'self-managed'
+ * only when every item is self-hosted-only, and 'normal' otherwise (a mix of
+ * conditional and/or unconditional items, each wrapped individually).
+ *
+ * @param {object} property - A property record, as extracted or overridden.
+ * @returns {{items: Array, sectionType: ('cloud'|'self-managed'|'normal')}}
+ */
+function seeAlsoView(property) {
+  const items = normalizeSeeAlso(property);
+  let sectionType = 'normal';
+  if (items.length > 0) {
+    if (items.every((item) => item.cloudOnly)) sectionType = 'cloud';
+    else if (items.every((item) => item.selfHostedOnly)) sectionType = 'self-managed';
+  }
+  return { items, sectionType };
+}
+
+module.exports = seeAlsoView;
+module.exports.normalizeSeeAlso = normalizeSeeAlso;

package/tools/property-extractor/property_extractor.py

@@ -1041,7 +1041,7 @@ def apply_property_overrides(properties, overrides, overrides_file_path=None):
     - Otherwise, searches existing properties for an entry whose `"name"` equals the override key and applies the override if found.
     - If no matching property is found, creates a new property from the override and adds it under the override key.
     
-    The function supports overrides that add or replace description, version, example content, default, type, config_scope, related_topics, and other metadata. When examples reference external files, relative paths are resolved relative to overrides_file_path.
+    The function supports overrides that add or replace description, version, example content, default, type, config_scope, see_also (related_topics is the deprecated predecessor, still read for existing overrides), and other metadata. When examples reference external files, relative paths are resolved relative to overrides_file_path.
     
     Parameters:
         properties (dict): Mapping of existing property entries (modified in-place).
@@ -1144,13 +1144,24 @@ def _apply_override_to_existing_property(property_dict, override, overrides_file
     if "config_scope" in override:
         property_dict["config_scope"] = override["config_scope"]
     
-    # Apply related_topics override
+    # Apply related_topics override (deprecated, see see_also)
     if "related_topics" in override:
         if isinstance(override["related_topics"], list):
             property_dict["related_topics"] = override["related_topics"]
         else:
             logger.warning(f"related_topics for property must be an array")
 
+    # Apply see_also override. Structural shape (plain string, or an object
+    # naming exactly one of cloud_only/self_hosted_only) is enforced by
+    # docs-data/property-overrides.schema.json via `doc-tools validate
+    # property-overrides`, not here — this just passes the data through for
+    # seeAlsoView.js to normalize at render time.
+    if "see_also" in override:
+        if isinstance(override["see_also"], list):
+            property_dict["see_also"] = override["see_also"]
+        else:
+            logger.warning(f"see_also for property must be an array")
+
     # Apply exclude_from_docs override
     if "exclude_from_docs" in override:
         property_dict["exclude_from_docs"] = override["exclude_from_docs"]
@@ -1192,19 +1203,26 @@ def _create_property_from_override(prop_name, override, overrides_file_path):
     if example_content:
         new_property["example"] = example_content
     
-    # Add related_topics if specified
+    # Add related_topics if specified (deprecated, see see_also)
     if "related_topics" in override:
         if isinstance(override["related_topics"], list):
             new_property["related_topics"] = override["related_topics"]
         else:
             logger.warning(f"related_topics for property '{prop_name}' must be an array")
-    
+
+    # Add see_also if specified
+    if "see_also" in override:
+        if isinstance(override["see_also"], list):
+            new_property["see_also"] = override["see_also"]
+        else:
+            logger.warning(f"see_also for property '{prop_name}' must be an array")
+
     # Add any other custom fields from override
     for key, value in override.items():
         if key not in ["description", "type", "default", "config_scope", "version",
                        "example", "example_file", "example_yaml", "related_topics",
-                       "is_deprecated", "visibility", "exclude_from_docs", "category",
-                       "accepted_values", "_comment"]:
+                       "see_also", "is_deprecated", "visibility", "exclude_from_docs",
+                       "category", "accepted_values", "_comment"]:
             new_property[key] = value
 
     # Add exclude_from_docs if specified

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

@@ -167,78 +167,66 @@ endif::[]
 |
 {{{example}}}
 {{/if}}
-{{#if related_topics}}
-{{#with (allTopicsConditional related_topics) as |sectionType|}}
+{{#with (seeAlsoView .) as |seeAlso|}}
+{{#if seeAlso.items.length}}
 
-{{#if (eq sectionType "cloud")}}
+{{#if (eq seeAlso.sectionType "cloud")}}
 ifdef::env-cloud[]
 | Related topics
-|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
+|{{#if (gt seeAlso.items.length 1)}}{{#each seeAlso.items}}
+* {{{content}}}
 {{/each}}
 {{else}}
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{{value}}}
-{{/with}}
+{{#each seeAlso.items}}
+{{{content}}}
 {{/each}}
 {{/if}}
 endif::[]
-{{else if (eq sectionType "self-managed")}}
+{{else if (eq seeAlso.sectionType "self-managed")}}
 ifndef::env-cloud[]
 | Related topics
-|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
+|{{#if (gt seeAlso.items.length 1)}}{{#each seeAlso.items}}
+* {{{content}}}
 {{/each}}
 {{else}}
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{{value}}}
-{{/with}}
+{{#each seeAlso.items}}
+{{{content}}}
 {{/each}}
 {{/if}}
 endif::[]
 {{else}}
 | Related topics
-|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{#if (eq type "cloud")}}
+|{{#if (gt seeAlso.items.length 1)}}{{#each seeAlso.items}}
+{{#if cloudOnly}}
 ifdef::env-cloud[]
-* {{{value}}}
+* {{{content}}}
 endif::[]
-{{else if (eq type "self-managed")}}
+{{else if selfHostedOnly}}
 ifndef::env-cloud[]
-* {{{value}}}
+* {{{content}}}
 endif::[]
 {{else}}
-* {{{value}}}
+* {{{content}}}
 {{/if}}
-{{/with}}
 {{/each}}
 {{else}}
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{#if (eq type "cloud")}}
+{{#each seeAlso.items}}
+{{#if cloudOnly}}
 ifdef::env-cloud[]
-{{{value}}}
+{{{content}}}
 endif::[]
-{{else if (eq type "self-managed")}}
+{{else if selfHostedOnly}}
 ifndef::env-cloud[]
-{{{value}}}
+{{{content}}}
 endif::[]
 {{else}}
-{{{value}}}
+{{{content}}}
 {{/if}}
-{{/with}}
 {{/each}}
 {{/if}}
 {{/if}}
-{{/with}}
 {{/if}}
+{{/with}}
 
 |===
 

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

@@ -130,78 +130,66 @@ endif::[]
 |
 {{{example}}}
 {{/if}}
-{{#if related_topics}}
-{{#with (allTopicsConditional related_topics) as |sectionType|}}
+{{#with (seeAlsoView .) as |seeAlso|}}
+{{#if seeAlso.items.length}}
 
-{{#if (eq sectionType "cloud")}}
+{{#if (eq seeAlso.sectionType "cloud")}}
 ifdef::env-cloud[]
 | Related topics
-|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
+|{{#if (gt seeAlso.items.length 1)}}{{#each seeAlso.items}}
+* {{{content}}}
 {{/each}}
 {{else}}
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{{value}}}
-{{/with}}
+{{#each seeAlso.items}}
+{{{content}}}
 {{/each}}
 {{/if}}
 endif::[]
-{{else if (eq sectionType "self-managed")}}
+{{else if (eq seeAlso.sectionType "self-managed")}}
 ifndef::env-cloud[]
 | Related topics
-|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-* {{{value}}}
-{{/with}}
+|{{#if (gt seeAlso.items.length 1)}}{{#each seeAlso.items}}
+* {{{content}}}
 {{/each}}
 {{else}}
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{{value}}}
-{{/with}}
+{{#each seeAlso.items}}
+{{{content}}}
 {{/each}}
 {{/if}}
 endif::[]
 {{else}}
 | Related topics
-|{{#if (gt (length ../related_topics) 1)}}{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{#if (eq type "cloud")}}
+|{{#if (gt seeAlso.items.length 1)}}{{#each seeAlso.items}}
+{{#if cloudOnly}}
 ifdef::env-cloud[]
-* {{{value}}}
+* {{{content}}}
 endif::[]
-{{else if (eq type "self-managed")}}
+{{else if selfHostedOnly}}
 ifndef::env-cloud[]
-* {{{value}}}
+* {{{content}}}
 endif::[]
 {{else}}
-* {{{value}}}
+* {{{content}}}
 {{/if}}
-{{/with}}
 {{/each}}
 {{else}}
-{{#each ../related_topics}}
-{{#with (parseRelatedTopic this)}}
-{{#if (eq type "cloud")}}
+{{#each seeAlso.items}}
+{{#if cloudOnly}}
 ifdef::env-cloud[]
-{{{value}}}
+{{{content}}}
 endif::[]
-{{else if (eq type "self-managed")}}
+{{else if selfHostedOnly}}
 ifndef::env-cloud[]
-{{{value}}}
+{{{content}}}
 endif::[]
 {{else}}
-{{{value}}}
+{{{content}}}
 {{/if}}
-{{/with}}
 {{/each}}
 {{/if}}
 {{/if}}
-{{/with}}
 {{/if}}
+{{/with}}
 {{#if aliases}}
 
 ifndef::env-cloud[]

package/tools/property-extractor/validate-overrides.js

@@ -0,0 +1,120 @@
+'use strict'
+
+const Ajv2020 = require('ajv/dist/2020')
+const fs = require('fs')
+const path = require('path')
+const { ValidationResult } = require('../../cli-utils/validation-result')
+
+/**
+ * Load and compile the JSON Schema for validation
+ * @param {string} [overridesPath] - Path to the overrides file; the schema is
+ *   looked up as a sibling (same directory) before falling back to the
+ *   package-relative path.
+ * @returns {Function} Compiled schema validator
+ */
+function loadSchemaValidator(overridesPath) {
+  // Primary: look for the schema next to the overrides file (docs repo's docs-data/).
+  if (overridesPath) {
+    const siblingPath = path.join(path.dirname(path.resolve(overridesPath)), 'property-overrides.schema.json')
+    if (fs.existsSync(siblingPath)) {
+      const schema = JSON.parse(fs.readFileSync(siblingPath, 'utf8'))
+      const ajv = new Ajv2020({ allErrors: true, verbose: true })
+      return ajv.compile(schema)
+    }
+  }
+
+  // Fallback: package-relative path (legacy / monorepo usage).
+  const schemaPath = path.resolve(__dirname, '../../docs-data/property-overrides.schema.json')
+
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Schema file not found: ${schemaPath}`)
+  }
+
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+  const ajv = new Ajv2020({ allErrors: true, verbose: true })
+  return ajv.compile(schema)
+}
+
+/**
+ * Validate overrides against the JSON Schema
+ * @param {Object} overrides - Overrides object to validate
+ * @param {string} [overridesPath] - Path to the overrides file (used to locate the schema)
+ * @returns {ValidationResult}
+ */
+function validateSchema(overrides, overridesPath) {
+  const result = new ValidationResult()
+
+  try {
+    const validate = loadSchemaValidator(overridesPath)
+    const valid = validate(overrides)
+
+    if (!valid) {
+      for (const error of validate.errors || []) {
+        const instancePath = error.instancePath || '/'
+        result.addError(error.message, instancePath)
+      }
+    }
+  } catch (err) {
+    result.addError(`Schema validation failed: ${err.message}`)
+  }
+
+  return result
+}
+
+/**
+ * Run all validations on a property-overrides object.
+ * @param {Object} overrides - Overrides object to validate
+ * @param {string} [overridesPath] - Path to the overrides file (used to locate the schema)
+ * @returns {ValidationResult}
+ */
+function validateOverrides(overrides, overridesPath = null) {
+  const result = new ValidationResult()
+
+  if (!overrides || typeof overrides !== 'object') {
+    result.addError('Overrides must be a non-null object')
+    return result
+  }
+
+  result.merge(validateSchema(overrides, overridesPath))
+
+  return result
+}
+
+/**
+ * Load and validate a property-overrides.json file.
+ * @param {string} overridesPath - Path to overrides JSON file
+ * @returns {{ overrides: Object|null, validation: ValidationResult }}
+ */
+function loadAndValidateOverrides(overridesPath) {
+  const validation = new ValidationResult()
+
+  if (!overridesPath) {
+    return { overrides: null, validation }
+  }
+
+  if (!fs.existsSync(overridesPath)) {
+    validation.addWarning(`Overrides file not found: ${overridesPath}`)
+    return { overrides: null, validation }
+  }
+
+  let overrides
+  try {
+    const content = fs.readFileSync(overridesPath, 'utf8')
+    overrides = JSON.parse(content)
+  } catch (err) {
+    validation.addError(`Failed to parse overrides JSON: ${err.message}`, overridesPath)
+    return { overrides: null, validation }
+  }
+
+  validation.merge(validateOverrides(overrides, overridesPath))
+
+  return { overrides, validation }
+}
+
+module.exports = {
+  ValidationResult,
+  loadSchemaValidator,
+  validateSchema,
+  validateOverrides,
+  loadAndValidateOverrides,
+}

package/tools/rpk-docs/validate-overrides.js

@@ -3,6 +3,7 @@
 const Ajv2020 = require('ajv/dist/2020')
 const fs = require('fs')
 const path = require('path')
+const { ValidationResult } = require('../../cli-utils/validation-result')
 
 /**
  * Valid admonition locations for notes, warnings, tips, cautions, importants
@@ -50,51 +51,6 @@ const VALID_SECTION_POSITIONS = [
   'end'
 ]
 
-/**
- * Validation result object
- */
-class ValidationResult {
-  constructor() {
-    this.valid = true
-    this.errors = []
-    this.warnings = []
-  }
-
-  addError(message, context = null) {
-    this.valid = false
-    this.errors.push({ message, context })
-  }
-
-  addWarning(message, context = null) {
-    this.warnings.push({ message, context })
-  }
-
-  merge(other) {
-    if (!other.valid) this.valid = false
-    this.errors.push(...other.errors)
-    this.warnings.push(...other.warnings)
-  }
-
-  format() {
-    const lines = []
-    if (this.errors.length > 0) {
-      lines.push('ERRORS:')
-      for (const err of this.errors) {
-        lines.push(`  ✗ ${err.message}`)
-        if (err.context) lines.push(`    at: ${err.context}`)
-      }
-    }
-    if (this.warnings.length > 0) {
-      lines.push('WARNINGS:')
-      for (const warn of this.warnings) {
-        lines.push(`  ⚠ ${warn.message}`)
-        if (warn.context) lines.push(`    at: ${warn.context}`)
-      }
-    }
-    return lines.join('\n')
-  }
-}
-
 /**
  * Normalize a command path (trim whitespace, collapse multiple spaces)
  * @param {string} cmdPath - Command path to normalize

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

@@ -1,19 +0,0 @@
-// Returns 'cloud' if all topics are cloud-only, 'self-managed' if all are self-managed-only, else 'normal'
-module.exports = function allTopicsConditional(related_topics) {
-  if (!Array.isArray(related_topics) || related_topics.length === 0) return null;
-  let allCloud = true;
-  let allSelfManaged = true;
-  for (const t of related_topics) {
-    if (typeof t !== 'string') {
-      allCloud = false;
-      allSelfManaged = false;
-      break;
-    }
-    const trimmed = t.trim();
-    if (!trimmed.startsWith('cloud-only:')) allCloud = false;
-    if (!trimmed.startsWith('self-managed-only:')) allSelfManaged = false;
-  }
-  if (allCloud) return 'cloud';
-  if (allSelfManaged) return 'self-managed';
-  return 'normal';
-};

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

@@ -1,13 +0,0 @@
-// Returns an object with type and value for a related topic
-// type: 'cloud', 'self-managed', or 'normal'
-module.exports = function parseRelatedTopic(topic) {
-  if (typeof topic !== 'string') return { type: 'normal', value: topic };
-  const trimmed = topic.trim();
-  if (trimmed.startsWith('cloud-only:')) {
-    return { type: 'cloud', value: trimmed.replace(/^cloud-only:/, '').trim() };
-  }
-  if (trimmed.startsWith('self-managed-only:')) {
-    return { type: 'self-managed', value: trimmed.replace(/^self-managed-only:/, '').trim() };
-  }
-  return { type: 'normal', value: trimmed };
-};