@redpanda-data/docs-extensions-and-macros 4.5.0 → 4.6.0

package/README.adoc

@@ -763,108 +763,6 @@ 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.
@@ -909,67 +807,6 @@ 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.