@redpanda-data/docs-extensions-and-macros 4.2.5 → 4.3.0

package/README.adoc

@@ -123,7 +123,7 @@ antora:
         - home:ROOT:attachment$custom-file.txt
 ----
 
-==== Registration example
+==== Registration
 
 [source,yaml]
 ----
@@ -155,7 +155,7 @@ Any elements, classes, or IDs that you want to exclude from the index.
 index-latest-only (optional)::
 Whether to index all versions or just the latest version of a component.
 
-==== Registration example
+==== Registration
 
 ```yaml
 antora:
@@ -246,7 +246,7 @@ This extension does not require any environment variables.
 
 There are no configurable options for this extension.
 
-==== Registration example
+==== Registration
 
 ```yaml
 antora:
@@ -297,7 +297,7 @@ antora:
             upgrade_doc: ROOT:upgrade:index.adoc
 ----
 
-==== Registration example
+==== Registration
 
 You can register the extension with a customized configuration for different components in your playbook:
 
@@ -456,7 +456,7 @@ NOTE: If you don't set the environment variable, the latest version of Redpanda
 
 There are no configurable options for this extension.
 
-==== Registration Example
+==== Registration
 
 ```yaml
 antora:
@@ -488,7 +488,7 @@ The following attributes are available to the latest version of the `ROOT` compo
 
 NOTE: If you don't set the environment variable, the latest versions may not be fetched. When the environment variable is not set, the extension sends unauthenticated requests to GitHub. Unauthenticated requests may result in hitting the API rate limit and cause GitHub to reject the request.
 
-==== Registration example
+==== Registration
 
 ```yaml
 antora:
@@ -508,7 +508,7 @@ This extension does not require any environment variables.
 
 There are no configurable options for this extension. It operates based on site attributes defined in `add-global-attributes.js` to determine valid categories and subcategories.
 
-==== Registration example
+==== Registration
 
 Register the `validate-attributes` extension in the Antora playbook under the `antora.extensions` key like so:
 
@@ -531,7 +531,7 @@ This extension operates without requiring any specific environment variables.
 
 This extension does not offer configurable options. It uses the inherent attributes of pages to determine relationships based on `page-categories` and deployment types (`env-kubernetes`, `env-linux`, `env-docker`, `page-cloud`).
 
-==== Registration example
+==== Registration
 
 To integrate the `related-docs-extension` into your Antora playbook, add it under the `antora.extensions` key as demonstrated below:
 
@@ -554,7 +554,7 @@ This extension does not require any environment variables.
 
 The extension operates without explicit configuration options. It automatically processes documentation pages to identify and link related labs based on shared `page-categories` attributes and deployment types (`env-kubernetes`, `env-linux`, `env-docker`, `page-cloud`).
 
-==== Registration example
+==== Registration
 
 Include the `related-labs-extension` in the Antora playbook under the `antora.extensions` key as follows:
 
@@ -579,7 +579,7 @@ The extension accepts the following configuration options:
 
 attributespath (optional):: Specifies the path to a local YAML file that contains global attributes. If this is provided, the extension will load attributes from this file first. If this path is not provided or no valid attributes are found in the file, the extension will fall back to loading attributes from the `shared` component.
 
-==== Registration example
+==== Registration
 
 ```yml
 antora:
@@ -602,7 +602,7 @@ This extension does not require any environment variables.
 
 There are no configurable options for this extension.
 
-==== Registration example
+==== Registration
 
 ```yaml
 antora:
@@ -640,7 +640,7 @@ data.replacements (required):: An array of replacement configurations. Each conf
 
 NOTE: Ensure that `file_patterns` accurately reflect the paths of the attachments you want to process. Overly broad patterns may include unintended files, while overly restrictive patterns might exclude necessary resources.
 
-==== Registration Example
+==== Registration
 
 This is an example of how to register and configure the `replace-attributes-in-attachments` extension in your Antora playbook. This example demonstrates defining multiple replacement configurations, each targeting different components and specifying their own file patterns and custom replacements.
 
@@ -698,7 +698,7 @@ Term files should follow the following structure:
 This is the detailed description of the term.
 ```
 
-==== Registration example
+==== Registration
 
 ```yml
 antora:
@@ -729,7 +729,7 @@ Whether to add unlisted pages to the navigation. The default is `false` (unliste
 unlistedPagesHeading (optional)::
 The heading under which to list the unlisted pages in the navigation. The default is 'Unlisted Pages'.
 
-==== Registration example
+==== Registration
 
 ```yaml
 antora:
@@ -749,7 +749,7 @@ IMPORTANT: Be sure to register each extension under the `asciidoc.extensions` ke
 
 This extension adds the necessary classes to make line numbers and line highlighting work with Prism.js.
 
-==== Registration example
+==== Registration
 
 ```yaml
 antora:
@@ -763,6 +763,108 @@ This section documents the Asciidoc macros that are provided by this library and
 
 IMPORTANT: Be sure to register each extension under the `asciidoc.extensions` key in the playbook, not the `antora.extensions` key.
 
+=== data_template
+
+The `data_template` block processor lets you render dynamic AsciiDoc content from external or local data sources (JSON, YAML, or plain text) using Handlebars templates.
+
+This is useful for generating documentation from structured data like config fields, component metadata, or examples.
+
+=== Usage
+
+You can use the `data_template` block macro to dynamically generate AsciiDoc content from structured data files such as JSON or YAML. The macro uses a Handlebars template to render the data.
+
+[source,asciidoc]
+----
+[data_template, ROOT:example$connect.json]
+--
+== Component: {{{name}}}
+
+Summary: {{{summary}}}
+
+{{#each fields}}
+=== {{name}}
+
+*Type*: `{{type}}`
+
+{{{description}}}
+{{/each}}
+--
+----
+
+The block content is a Handlebars template. Fields from the data file are injected into this template during site build.
+
+The macro accepts one or two positional attributes:
+
+1. The first attribute (`dataPath`) is required and should be the resource ID of the data file.
+2. The second attribute (`overrides`) is optional and allows you to override or merge values from a secondary file.
+
+You can apply overrides by specifying a second file:
+
+[source,asciidoc]
+----
+[data_template, ROOT:example$connect.json, ROOT:example$overrides.json]
+--
+...template content...
+--
+----
+
+In this case:
+
+- The macro first loads and parses `connect.json`.
+- Then it loads `overrides.json` and **merges** its values into the base file.
+- Arrays of objects (such as fields or processors) are merged by matching objects with the same `name` key.
+- The result is passed into the Handlebars template.
+
+This is useful for tweaking content (like updating a `description`) without modifying the original source file.
+
+==== Triple mustaches
+
+When your data contains AsciiDoc markup (like lists, admonitions, or headings), use triple curly braces:
+
+[source,handlebars]
+----
+{{{description}}}
+----
+
+This tells Handlebars to not escape the content, so Asciidoctor can render it correctly.
+
+==== Handlebars helpers
+
+The following helpers are available inside templates:
+
+* `eq`, `ne` — Equality helpers.
+* `uppercase` — Converts text to uppercase.
+* `renderConnectFields` — Renders config fields for Redpanda Connect.
+* `renderConnectExamples` — Renders usage examples.
+* `selectByJsonPath` — Selects items from the data using a JSONPath expression.
+
+==== Registration
+
+To use this macro, register it in your Antora playbook:
+
+[source,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/data-template'
+----
+
+==== Example
+
+You can use the `selectByJsonPath` helper to filter data. For example, if you want to render only the `redis` processor's fields from a JSON file, you can do it like this:
+
+[source,asciidoc]
+----
+[data_template, redpanda-connect:ROOT:example$connect.json]
+--
+{{#selectByJsonPath this "$.processors[?(@.name=='redis')]" }}
+{{renderConnectFields this.config.children}}
+{{/selectByJsonPath}}
+--
+----
+
+This will render only the fields for the `redis` processor.
+
 === config_ref
 
 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.
@@ -798,7 +900,7 @@ For example:
 config_ref:example_config,true,tunable-properties[]
 ----
 
-==== Registration example
+==== Registration
 
 [,yaml]
 ----
@@ -807,6 +909,67 @@ asciidoc:
     - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
 ----
 
+=== data_template
+
+The `data_template` macro provides a way to dynamically generate AsciiDoc content by combining external or local data sources with Handlebars templates. When you use the `data_template` block macro, the extension performs the following steps:
+
+* Resolves the `dataPath` attribute to locate a data file (in JSON, YAML, or raw text format).
+* Fetches and caches external resources or reads local files from the Antora content catalog.
+* Parses the data file.
+* Compiles the block's content as a Handlebars template, injecting the parsed data.
+* Processes the resulting text as AsciiDoc using Asciidoctor to generate the final HTML output.
+
+By default, Handlebars escapes HTML to prevent potential security issues. However, if your data includes AsciiDoc markup (such as headings, lists, or formatting directives), escaping it will prevent Asciidoctor from converting the markup correctly.
+
+To ensure that your AsciiDoc syntax is preserved during template rendering, **use the triple curly braces syntax** in your Handlebars templates. For example, if your JSON file contains a `description` field with AsciiDoc content, reference it like this:
+
+[source,handlebars]
+----
+{{{description}}}
+----
+
+This tells Handlebars to output the content unescaped, allowing Asciidoctor to process the raw AsciiDoc markup correctly.
+
+==== Usage
+
+In an AsciiDoc document, you can invoke the data template macro as follows:
+
+[,asciidoc]
+----
+[data_template, ROOT:example$connect.json]
+--
+Version: {{{version}}}
+
+{{#each buffers}}
+
+=== {{{this.name}}}
+
+Status: {{{this.status}}}
+
+{{#if (eq this.name 'memory')}}
+This is a custom description for the memory buffer.
+{{else}}
+{{{this.summary}}}
+{{/if}}
+
+{{/each}}
+
+--
+----
+
+==== Registration
+
+Register the macro in your Antora playbook under the `asciidoc.extensions` key:
+
+[source,yaml]
+----
+asciidoc:
+  extensions:
+    - require: '@redpanda-data/docs-extensions-and-macros/macros/data-template'
+----
+
+This configuration ensures that during the build process, the data template macro is executed to fetch, parse, and render data as part of your docs.
+
 === glossterm
 
 The `glossterm` inline macro provides a way to define and reference glossary terms in your AsciiDoc documents.
@@ -855,7 +1018,7 @@ Whether to enable tooltips for the defined terms. Valid values are:
 
 The last two options are intended to support js/css tooltip solutions such as tippy.js.
 
-==== Registration example
+==== Registration
 
 [,yaml]
 ----
@@ -897,7 +1060,7 @@ For default values and documentation for configuration options, see the https://
 
 If you do not specify a Helm reference value, the macro generates a link without specifying a path.
 
-==== Registration example
+==== Registration
 
 [,yaml]
 ----
@@ -918,7 +1081,7 @@ The categories are fetched from the `connectCategoriesData` that's generated in
 components_by_category::[<type>]
 ```
 
-==== Registration example
+==== Registration
 
 ```yaml
 asciidoc:
@@ -938,7 +1101,7 @@ The types are fetched from the `flatComponentsData` that's generated in the <<Co
 component_table::[]
 ```
 
-==== Registration example
+==== Registration
 
 ```yaml
 asciidoc:
@@ -958,7 +1121,7 @@ The types are fetched from the `flatComponentsData` that's generated in the <<Co
 component_type_dropdown::[]
 ```
 
-==== Registration example
+==== Registration
 
 ```yaml
 asciidoc:

package/macros/data-template.js

@@ -0,0 +1,591 @@
+'use strict';
+
+/**
+ * data_template macro for Asciidoctor.js
+ *
+ * This module defines a [data_template] block macro that leverages Handlebars templates to allow us to reference data in JSON or YAML files directly inside Asciidoc pages.
+ * It processes external or local data sources (in JSON, YAML, or raw text), compiles a Handlebars template
+ * provided within the block, and then parses the resulting content as AsciiDoc using Asciidoctor.
+ */
+
+// This global Opal object is available because Antora uses Asciidoctor.js (compiled using Opal) to convert AsciiDoc into HTML.
+const loggerLib = require('@antora/logger');
+loggerLib.configure({
+  format: 'pretty',
+  level: 'error'
+});
+const path = require('path').posix;
+const logger = loggerLib.getLogger('data-template');
+const handlebars = require('handlebars');
+const loadAsciiDoc = require('@antora/asciidoc-loader')
+const jsonpath = require('jsonpath-plus');
+const yaml = require('yaml');
+// For synchronous HTTP fetching.
+const request = require('sync-request');
+const computeOut = require('../util/compute-out.js');
+const createAsciiDocFile = require('../util/create-asciidoc-file.js');
+
+// In-memory cache for external resources (avoid repeated network calls)
+const externalCache = new Map();
+
+// ========= Handlebars helpers =============
+
+/**
+ * Converts a string to uppercase.
+ *
+ * @param {string} str - The string to convert.
+ * @returns {string} The uppercase version of the input string.
+ */
+function uppercase(str) {
+  return String(str).toUpperCase();
+}
+
+/**
+ * Checks if two values are equal.
+ *
+ * @param {*} a - The first value.
+ * @param {*} b - The second value.
+ * @returns {string} True if the values are equal.
+ */
+function eq(a, b) {
+  if (a === b) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Checks if two values are not equal.
+ *
+ * @param {*} a - The first value.
+ * @param {*} b - The second value.
+ * @returns {string} False if the values are not equal.
+ */
+function ne(a, b) {
+  if (a !== b) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Renders the children of a configuration object.
+ *
+ * @param {Array<Object>} children - An array of child objects.
+ * @returns {string} The rendered string containing the configuration details.
+ */
+function renderConnectFields(children, prefix = '') {
+  if (!children || !Array.isArray(children) || children.length === 0) {
+    return '';
+  }
+
+  let output = '';
+  prefix = typeof prefix === 'string' ? prefix : '';
+
+  children.forEach(child => {
+    const isArray = child.kind === 'array';
+    if (!child.name) return;
+    const currentPath = prefix ? `${prefix}.${child.name}${isArray ? '[]' : ''}` : `${child.name}${isArray ? '[]' : ''}`;
+
+    // Section header for the field.
+    output += `=== \`${currentPath}\`\n\n`;
+
+    // Append description if available.
+    if (child.description) {
+      output += `${child.description}\n\n`;
+    }
+
+    // Inject admonition if the config is secret.
+    if (child.is_secret === true) {
+      output += `include::redpanda-connect:components:partial$secret_warning.adoc[]\n\n`;
+    }
+
+    // Insert version requirement if a version is provided.
+    if (child.version) {
+      output += `Requires version ${child.version} or later.\n\n`;
+    }
+
+    // Append type.
+    output += `*Type*: \`${child.type}\`\n\n`;
+
+    // For non-object types, output the default value if present.
+    if (child.type !== 'object' && child.default !== undefined) {
+      if (child.default === "") {
+        output += `*Default*: \`""\`\n\n`;
+      } else {
+        output += `*Default*: \`${child.default}\`\n\n`;
+      }
+    }
+
+    // If annotated_options is present, build the AsciiDoc table.
+    if (child.annotated_options && Array.isArray(child.annotated_options) && child.annotated_options.length > 0) {
+      output += "[cols=\"1m,2a\"]\n";
+      output += "|===\n";
+      output += "|Option |Summary\n\n";
+      child.annotated_options.forEach(optionPair => {
+        // Ensure each optionPair is an array with at least two items:
+        if (Array.isArray(optionPair) && optionPair.length >= 2) {
+          output += `|${optionPair[0]}\n|${optionPair[1]}\n\n`;
+        }
+      });
+      output += "|===\n\n";
+    }
+
+    if (child.options && Array.isArray(child.options) && child.options.length > 0) {
+      output += `*Options*: ${child.options.map(option => `\`${option}\``).join(', ')}\n\n`;
+    }
+    
+
+    // If examples are provided, add a fenced YAML block.
+    if (child.examples) {
+      output += "```yaml\n";
+      output += "# Examples:\n";
+
+      // Branch for string fields.
+      if (child.type === 'string') {
+        // If the field is an array of strings.
+        if (child.kind === 'array') {
+          child.examples.forEach(exampleGroup => {
+            output += `${child.name}:\n`;
+            if (Array.isArray(exampleGroup)) {
+              exampleGroup.forEach(exampleValue => {
+                if (typeof exampleValue === 'string' && exampleValue.includes('\n')) {
+                  // Use literal block syntax for multi-line strings.
+                  output += `  - |-\n`;
+                  let indentedLines = exampleValue
+                    .split('\n')
+                    .map(line => '      ' + line)
+                    .join('\n');
+                  output += `${indentedLines}\n`;
+                } else {
+                  output += `  - ${exampleValue}\n`;
+                }
+              });
+            } else {
+              // Fallback for single value example group.
+              if (typeof exampleGroup === 'string' && exampleGroup.includes('\n')) {
+                output += `  - |-\n`;
+                let indentedLines = exampleGroup
+                  .split('\n')
+                  .map(line => '      ' + line)
+                  .join('\n');
+                output += `${indentedLines}\n`;
+              } else {
+                output += `  - ${exampleGroup}\n`;
+              }
+            }
+            output += "\n";
+          });
+        } else {
+          // For non-array string examples, output them as key/value pairs.
+          child.examples.forEach(example => {
+            if (example.includes('\n')) {
+              output += `${child.name}: |-\n`;
+              let indentedLines = example.split('\n').map(line => '  ' + line).join('\n');
+              output += `${indentedLines}\n`;
+            } else {
+              output += `${child.name}: ${example}\n`;
+            }
+          });
+        }
+      }
+      // Branch for processor fields.
+      else if (child.type === 'processor') {
+        if (child.kind === 'array') {
+          child.examples.forEach(exampleGroup => {
+            output += `${child.name}:\n`;
+            if (Array.isArray(exampleGroup)) {
+              exampleGroup.forEach(exampleObj => {
+                let yamlSnippet = yaml.stringify(exampleObj).trim();
+                let lines = yamlSnippet.split('\n');
+                let formattedLines = lines.map((line, idx) => {
+                  return idx === 0 ? "  - " + line : "    " + line;
+                }).join('\n');
+                output += formattedLines + "\n";
+              });
+            } else {
+              let yamlSnippet = yaml.stringify(exampleGroup).trim();
+              let lines = yamlSnippet.split('\n');
+              let formattedLines = lines.map((line, idx) => {
+                return idx === 0 ? "  - " + line : "    " + line;
+              }).join('\n');
+              output += formattedLines + "\n";
+            }
+            output += "\n";
+          });
+        } else {
+          child.examples.forEach(example => {
+            output += `${child.name}: ${example}\n`;
+          });
+        }
+      }
+      // Branch for object fields.
+      else if (child.type === 'object') {
+        // If this object is actually an array of objects.
+        if (child.kind === 'array') {
+          child.examples.forEach(exampleGroup => {
+            output += `${child.name}:\n`;
+            if (Array.isArray(exampleGroup)) {
+              exampleGroup.forEach(exampleObj => {
+                let yamlSnippet = yaml.stringify(exampleObj).trim();
+                let lines = yamlSnippet.split('\n');
+                let formattedLines = lines.map((line, idx) => {
+                  return idx === 0 ? "  - " + line : "    " + line;
+                }).join('\n');
+                output += formattedLines + "\n";
+              });
+            } else {
+              let yamlSnippet = yaml.stringify(exampleGroup).trim();
+              let lines = yamlSnippet.split('\n');
+              let formattedLines = lines.map((line, idx) => {
+                return idx === 0 ? "  - " + line : "    " + line;
+              }).join('\n');
+              output += formattedLines + "\n";
+            }
+            output += "\n";
+          });
+        } else {
+          // Fallback for non-array object examples.
+          child.examples.forEach(example => {
+            if (typeof example === 'object') {
+              let yamlSnippet = yaml.stringify(example).trim();
+              let lines = yamlSnippet.split('\n');
+              let formattedLines = lines.map((line, idx) => idx === 0 ? line : "  " + line).join('\n');
+              output += `${child.name}:\n${formattedLines}\n`;
+            } else {
+              output += `${child.name}: ${example}\n`;
+            }
+          });
+        }
+      }
+      // Fallback for any other field types.
+      else {
+        child.examples.forEach(example => {
+          output += `${child.name}: ${example}\n`;
+        });
+      }
+
+      output += "```\n\n";
+    }
+
+    // Recursively render any nested children.
+    if (child.children && Array.isArray(child.children) && child.children.length > 0) {
+      output += renderConnectFields(child.children, currentPath);
+    }
+  });
+
+  // Return a SafeString so that Handlebars doesn't escape special characters.
+  return new handlebars.SafeString(output);
+}
+
+/**
+ * Renders a list of examples.
+ *
+ * @param {Array<Object>} examples - An array of example objects.
+ * @returns {string} The rendered string containing the examples.
+ */
+function renderConnectExamples(examples) {
+  // If there are no examples, return an empty string.
+  if (!examples || !Array.isArray(examples) || examples.length === 0) {
+    return '';
+  }
+  // Start with a level-2 heading for all examples.
+  let output = '';
+  // Iterate over each example.
+  examples.forEach(example => {
+    // Render the example title as a level-3 heading.
+    if (example.title) {
+      output += `=== ${example.title}\n\n`;
+    }
+
+    // Render the summary if provided.
+    if (example.summary) {
+      output += `${example.summary}\n\n`;
+    }
+
+    // Render the example config inside an AsciiDoc code block.
+    // Using a [source,yaml] block and "----" as delimiters.
+    if (example.config) {
+      output += `[source,yaml]\n----\n`;
+      output += example.config.trim() + "\n";
+      output += "----\n\n";
+    }
+  });
+  // Return as a SafeString so that Handlebars doesn't escape markup.
+  return new handlebars.SafeString(output);
+}
+
+/**
+ * Selects data from a JSON object using a JSONPath expression.
+ *
+ * @param {Object} context - The JSON object to query.
+ * @param {string} pathExpression - The JSONPath expression to use for selection.
+ * @param {Object} options - Handlebars options object.
+ * @returns {string} The rendered string containing the selected data.
+ */
+
+function selectByJsonPath(context, pathExpression, options) {
+  // Query the context with the provided JSONPath expression.
+  pathExpression = (typeof pathExpression === 'string' && pathExpression !== '') ? pathExpression : "$";
+  const results = jsonpath.JSONPath({ path: pathExpression, json: context });
+  // If no results are found, render the inverse block.
+  if (!results || results.length === 0) {
+    return options.inverse ? options.inverse(this) : '';
+  }
+
+  // If exactly one result is found, use that as the context.
+  if (results.length === 1) {
+    return options.fn(results[0]);
+  }
+
+  // Otherwise, if multiple results are found, iterate over them.
+  let resultString = '';
+  results.forEach(result => {
+    resultString += options.fn(result);
+  });
+  return resultString;
+}
+
+// Register all helpers with Handlebars
+handlebars.registerHelper('uppercase', uppercase);
+handlebars.registerHelper('eq', eq);
+handlebars.registerHelper('ne', ne);
+handlebars.registerHelper('renderConnectFields', renderConnectFields);
+handlebars.registerHelper('renderConnectExamples', renderConnectExamples);
+handlebars.registerHelper('selectByJsonPath', selectByJsonPath);
+
+
+
+// ============= End of helpers ===========================
+
+
+/**
+ * Recursively merges properties from the `overrides` object into the `target` object.
+ *
+ * - If both `target[key]` and `overrides[key]` are arrays, it matches each item in `target` with an item in `overrides`
+ *   that has the same `name` property, then merges selected fields and also recursively processes nested objects.
+ * - If both `target[key]` and `overrides[key]` are plain objects, it merges them recursively.
+ * - Otherwise, it simply replaces `target[key]` with `overrides[key]`.
+ *
+ * @param {Object} target   The object into which overrides will be merged.
+ * @param {Object} overrides The object containing override properties.
+ * @returns {Object}        The updated `target` object.
+ */
+function mergeOverrides(target, overrides) {
+  if (!overrides || typeof overrides !== 'object') return target;
+
+  for (let key in overrides) {
+    // Handle arrays by matching items on 'name'
+    if (Array.isArray(target[key]) && Array.isArray(overrides[key])) {
+      target[key] = target[key].map(item => {
+        const overrideItem = overrides[key].find(o => o.name === item.name);
+        if (overrideItem) {
+          // Only override allowed fields if they are explicitly defined
+          ['description', 'type'].forEach(field => {
+            if (overrideItem.hasOwnProperty(field)) {
+              item[field] = overrideItem[field];
+            }
+          });
+
+          // Recursively handle nested children
+          item = mergeOverrides(item, overrideItem);
+        }
+        return item;
+      });
+
+    // Recurse into nested objects
+    } else if (
+      typeof target[key] === 'object' &&
+      typeof overrides[key] === 'object' &&
+      !Array.isArray(target[key]) &&
+      !Array.isArray(overrides[key])
+    ) {
+      target[key] = mergeOverrides(target[key], overrides[key]);
+
+    // Only override top-level description/type if defined in overrides
+    } else if (['description', 'type'].includes(key) && overrides.hasOwnProperty(key)) {
+      target[key] = overrides[key];
+    }
+  }
+  return target;
+}
+
+
+function processData_TemplateBlock(parent, reader, attrs, config, extensionRef) {
+  const catalog = config.contentCatalog;
+  if (!catalog) {
+    logger.error('[data_template] Error: content catalog not found');
+    return extensionRef.createBlock(parent, 'paragraph', 'Error: content catalog not found', attrs);
+  }
+
+  // The dataPath may be an Antora resource ID (for local files)
+  // or an external URL (like https://example.com/data.json)
+  const resourceId = attrs.dataPath;
+  if (!resourceId) {
+    const msg = '[data_template] Error: No data resource ID provided.';
+    return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+  }
+
+  let contentStr;
+  let ext = '';
+
+  if (resourceId.startsWith('http://') || resourceId.startsWith('https://')) {
+    // Handle external resource
+    try {
+      if (externalCache.has(resourceId)) {
+        contentStr = externalCache.get(resourceId);
+      } else {
+        const res = request('GET', resourceId, { timeout: 5000 });
+        contentStr = res.getBody('utf8');
+        externalCache.set(resourceId, contentStr);
+      }
+      // Determine file extension from the URL’s pathname.
+      try {
+        const urlObj = new URL(resourceId);
+        const pathname = urlObj.pathname;
+        ext = pathname.substring(pathname.lastIndexOf('.')).toLowerCase();
+      } catch (err) {
+        ext = '';
+      }
+    } catch (err) {
+      const msg = `[data_template] Error fetching external resource: ${err}`;
+      return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+    }
+  } else {
+    // Handle local resource using Antora's content catalog.
+    const fileSrc = config.file && config.file.src;
+    const resourceFile = catalog.resolveResource(resourceId, fileSrc);
+    if (!resourceFile) {
+      const msg = `[data_template] Could not resolve resource: ${resourceId}`;
+      return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+    }
+    try {
+      contentStr = resourceFile.contents.toString();
+      ext = resourceFile.src.extname.toLowerCase();
+    } catch (err) {
+      const msg = `[data_template] Error reading local resource: ${err}`;
+      return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+    }
+  }
+
+  // Load and parse the data from the resource.
+  let dataObj = null;
+  try {
+    if (ext === '.json') {
+      dataObj = JSON.parse(contentStr);
+    } else if (ext === '.yaml' || ext === '.yml') {
+      dataObj = yaml.parse(contentStr);
+    } else {
+      // Fallback: try JSON first, then yaml, then default to raw text.
+      try {
+        dataObj = JSON.parse(contentStr);
+      } catch (jsonErr) {
+        try {
+          dataObj = yaml.parse(contentStr);
+        } catch (yamlErr) {
+          dataObj = { text: contentStr };
+        }
+      }
+    }
+  } catch (err) {
+    const msg = `[data_template] Error parsing data: ${err}`;
+    return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+  }
+
+  if (attrs.overrides) {
+    try {
+      const overridesFile = catalog.resolveResource(attrs.overrides, config.file.src);
+      if (overridesFile) {
+        const overridesStr = overridesFile.contents.toString();
+        const overridesObj = JSON.parse(overridesStr);
+        dataObj = mergeOverrides(dataObj, overridesObj);
+      }
+    } catch (err) {
+      logger.error(`[data_template] Error applying overrides: ${err}`);
+    }
+  }
+  dataObj.__rawYAML = contentStr;
+
+  // Compile the Handlebars template from the block’s content.
+  let templateSource = reader.getLines().join('\n');
+  templateSource = templateSource.replace(/@@tab-content@@/g, '--')
+  let compiledText = '';
+  try {
+    const template = handlebars.compile(templateSource);
+    compiledText = template(dataObj);
+  } catch (err) {
+    const msg = `[data_template] Handlebars error: ${err}`;
+    return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+  }
+
+  // The following block takes the Handlebars-generated AsciiDoc content (`compiledText`)
+  // and parses it in the context of the parent document (`doc`). This is important
+  // because it allows Antora’s custom include logic and other extensions to be applied
+  // to the content as if it were part of the original AsciiDoc source. After parsing
+  // and converting the new document, we append the resulting blocks back into the
+  // parent node, merging the dynamically generated content into the final
+  // output. Any errors during parsing are caught and reported as a paragraph block.
+  try {
+    const sourceFile = config.file?.src;
+    const baseDir = sourceFile?.relative ? path.dirname(sourceFile.relative) : 'fragments';
+    const uniqueName = `data_template-${Date.now()}.adoc`;
+    const relativePath = path.join(baseDir, uniqueName);
+    const doc = parent.getDocument();
+    const attributes = doc.getAttributes()
+
+    const file = {
+      contents: Buffer.from(`${compiledText}`),
+      src: {
+        component: attributes['page-component-name'],
+        version: attributes['page-component-version'],
+        module: attributes['page-module'],
+        family: 'page',
+        relative: relativePath,
+      },
+    };
+    try {
+      file.out = computeOut.call(config.contentCatalog, file.src)
+      const outFile = createAsciiDocFile(config.contentCatalog, file);
+      const newDoc = loadAsciiDoc(outFile, config.contentCatalog, {
+        ...doc.getOptions(),
+        relativizeResourceRefs: true,
+        attributes: {
+          ...(doc.getOptions().attributes || {}),
+          ...(attributes || {}),
+        },
+      });
+      newDoc.getBlocks().forEach((b) => {
+        parent.append(b);
+      });
+      return null;
+    } catch (err) {
+      console.warn('❌ loadAsciiDoc threw:', err);
+      return extensionRef.createBlock(parent, 'paragraph', `[data_template] loadAsciiDoc error: ${err.message}`, attrs);
+    }
+  } catch (err) {
+    const msg = `[data_template] Error parsing compiled template as AsciiDoc: ${err}`;
+    return extensionRef.createBlock(parent, 'paragraph', msg, attrs);
+  }
+}
+
+module.exports.register = (registry, context) => {
+  if (!registry && context) return;
+
+  const toProc = (fn) => Object.defineProperty(fn, '$$arity', { value: fn.length });
+
+  function createExtensionGroup({ contentCatalog, file }) {
+    return function () {
+      this.block('data_template', function () {
+        this.positionalAttributes(['dataPath', 'overrides']);
+        this.onContext('open');
+        this.process((parent, reader, attrs) => {
+          return processData_TemplateBlock(parent, reader, attrs, { contentCatalog, file }, this);
+        });
+      });
+    };
+  }
+
+  registry.$groups().$store('data-template-ext', toProc(createExtensionGroup(context)));
+  return registry
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.2.5",
+  "version": "4.3.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -50,7 +50,8 @@
     "./macros/glossary": "./macros/glossary.js",
     "./macros/rp-connect-components": "./macros/rp-connect-components.js",
     "./macros/config-ref": "./macros/config-ref.js",
-    "./macros/helm-ref": "./macros/helm-ref.js"
+    "./macros/helm-ref": "./macros/helm-ref.js",
+    "./macros/data-template": "./macros/data-template.js"
   },
   "files": [
     "extensions",
@@ -71,15 +72,19 @@
     "chalk": "4.1.2",
     "gulp": "^4.0.2",
     "gulp-connect": "^5.7.0",
+    "handlebars": "^4.7.8",
     "html-entities": "2.3",
     "js-yaml": "^4.1.0",
+    "jsonpath-plus": "^10.3.0",
     "lodash": "^4.17.21",
     "micromatch": "^4.0.8",
     "node-fetch": "^3.3.2",
     "node-html-parser": "5.4.2-0",
     "papaparse": "^5.4.1",
     "semver": "^7.6.0",
-    "tar": "^7.4.3"
+    "sync-request": "^6.1.0",
+    "tar": "^7.4.3",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
     "@antora/cli": "3.1.4",