@redpanda-data/docs-extensions-and-macros 5.54.0 → 5.56.0

package/extensions/version-fetcher/set-latest-version.js

@@ -8,6 +8,7 @@ module.exports.register = function ({ config }) {
   const GetLatestDockerTag = require('./fetch-latest-docker-tag');
   const GetLatestHelmChartVersionFromOperator = require('./get-latest-redpanda-helm-version-from-operator');
   const GetLatestConnectVersion = require('./get-latest-connect');
+  const { latestStablePerLine, releaseLineOf, isOlderReleaseLine } = require('./release-lines');
   const logger = this.getLogger('set-latest-version-extension');
 
   const { getGitHubApiToken } = require('../../cli-utils/github-token');
@@ -55,7 +56,14 @@ module.exports.register = function ({ config }) {
         // pre-freeze version forever.
         GetLatestRedpandaVersion(github, owner, 'streaming-enterprise', logger),
         GetLatestDockerTag(dockerNamespace, 'console', logger),
-        GetLatestDockerTag(dockerNamespace, 'redpanda-operator', logger),
+        // Three pages (300 tags) so older docs versions can still find the
+        // newest patch of their own operator line. Docker Hub lists recent
+        // pushes first, so the first page holds every line that still gets
+        // patches. Today the second and third pages add only legacy lines
+        // (2.x, 22.3, 23.x) that no built docs version pins to. They are
+        // headroom for a line that stops getting patches and drops off the
+        // first page as newer tags are pushed.
+        GetLatestDockerTag(dockerNamespace, 'redpanda-operator', logger, { maxPages: 3 }),
         GetLatestConnectVersion(github, owner, 'connect', logger),
       ]);
       
@@ -97,6 +105,33 @@ module.exports.register = function ({ config }) {
       };
 
       const components = await contentCatalog.getComponents();
+
+      // An operator or Helm chart release supports only its own Redpanda line
+      // and the lines next to it, so a docs version for an older line must
+      // install that line's release, not the newest one. Resolve the newest
+      // operator tag of each line from the fetched tags, and that line's chart
+      // version from its release branch, once per line.
+      const operatorLines = latestStablePerLine(latestVersions.operator?.stableReleases);
+      const lineVersions = new Map();
+      for (const component of components) {
+        for (const { version } of component.versions) {
+          if (!isOlderReleaseLine(version, component.latest?.version)) continue;
+          const line = releaseLineOf(version);
+          if (lineVersions.has(line)) continue;
+          const operatorTag = operatorLines.get(line) || null;
+          lineVersions.set(line, { operator: operatorTag, helmChart: null });
+        }
+      }
+      await Promise.all([...lineVersions].map(async ([line, resolved]) => {
+        if (!resolved.operator) return;
+        try {
+          const chart = await GetLatestHelmChartVersionFromOperator(github, owner, 'redpanda-operator', resolved.operator, null, logger);
+          resolved.helmChart = chart?.latestStableRelease || null;
+        } catch (error) {
+          logger.warn(`Helm chart lookup for the ${line} line failed: ${error.message || error}`);
+        }
+      }));
+
       components.forEach(component => {
         const prerelease = component.latestPrerelease;
 
@@ -105,13 +140,45 @@ module.exports.register = function ({ config }) {
             asciidoc.attributes['page-component-version-is-prerelease'] = 'true';
           }
 
+          // Older docs versions get the newest operator and chart release of
+          // their own line. The latest version, prereleases, and unversioned
+          // components get the newest release overall. When an older line has
+          // no release to pin to, the newest release would not support it, so
+          // the version keeps the value its antora.yml sets, and gets the
+          // newest release only when antora.yml sets nothing.
+          let operatorVersion = latestVersions.operator?.latestStableRelease;
+          let helmChartVersion = latestVersions.helmChart?.latestStableRelease;
+          if (isOlderReleaseLine(version, component.latest?.version)) {
+            const line = releaseLineOf(version);
+            const resolved = lineVersions.get(line) || {};
+            const keepOrNewest = (key, newest, what) => {
+              const own = asciidoc.attributes[key];
+              if (own) {
+                logger.warn(`No ${what} release found for the ${line} line, so ${name} ${version} keeps ${key} from its antora.yml (${own}).`);
+                return own;
+              }
+              logger.warn(`No ${what} release found for the ${line} line and its antora.yml sets no ${key}, so ${name} ${version} uses the newest release (${newest || 'unknown'}).`);
+              return newest;
+            };
+            if (resolved.operator) {
+              operatorVersion = resolved.operator;
+            } else {
+              operatorVersion = keepOrNewest('latest-operator-version', operatorVersion, 'stable Redpanda Operator');
+            }
+            if (resolved.helmChart) {
+              helmChartVersion = resolved.helmChart;
+            } else {
+              helmChartVersion = keepOrNewest('latest-redpanda-helm-chart-version', helmChartVersion, 'Redpanda Helm chart');
+            }
+          }
+
           // Set operator and helm chart attributes via helper function. These keep
           // their raw fetched form, including the "v" prefix on
           // latest-operator-version, because docs pages pass that value straight
           // to `helm --version`. Only the short sibling is derived.
           updateAttributes(asciidoc, [
-            { condition: latestVersions.operator, key: 'latest-operator-version', value: latestVersions.operator?.latestStableRelease },
-            { condition: latestVersions.helmChart, key: 'latest-redpanda-helm-chart-version', value: latestVersions.helmChart?.latestStableRelease }
+            { condition: latestVersions.operator, key: 'latest-operator-version', value: operatorVersion },
+            { condition: latestVersions.helmChart, key: 'latest-redpanda-helm-chart-version', value: helmChartVersion }
           ]);
 
           // Set attributes for console and connect versions
@@ -190,6 +257,9 @@ module.exports.register = function ({ config }) {
       summary.forEach(([label, stableVersion, betaVersion]) => {
         logger.info(`- ${label}: ${stableVersion || 'unknown'}${betaVersion ? ', beta: ' + betaVersion : ''}`);
       });
+      [...lineVersions].sort(([a], [b]) => semver.rcompare(`${a}.0`, `${b}.0`)).forEach(([line, resolved]) => {
+        logger.info(`- ${line} docs: operator ${resolved.operator || 'antora.yml value (no release in line)'}, Helm chart ${resolved.helmChart || 'antora.yml value (no release in line)'}`);
+      });
     } catch (error) {
       logger.error(`Error updating versions: ${error}`);
     }

package/macros/README.adoc

@@ -64,6 +64,7 @@ IMPORTANT: Macros must be registered under the `asciidoc.extensions` key in your
 
 === Block macros
 
+* **iceberg-explorer** - Emit a mount point that docs-ui hydrates into the interactive Iceberg Mode Explorer
 * **components_by_category** - Display Redpanda Connect components grouped by category
 * **component_table** - Generate searchable component tables
 * **component_type_dropdown** - Create dropdown for component types

package/macros/REFERENCE.adoc

@@ -430,6 +430,105 @@ asciidoc:
     - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
 ----
 
+== iceberg-explorer
+
+This macro registers an `[iceberg-explorer]` block that emits a version-aware mount point for the interactive Iceberg Mode Explorer:
+
+[,html]
+----
+<div class="iceberg-explorer-mount" data-iceberg-explorer="1" data-version="26.2">
+  <p class="iceberg-explorer-fallback">Interactive Iceberg Mode Explorer. If this text is still here...</p>
+</div>
+----
+
+The block renders the container only. The explorer UI and its translation engine live in the docs-ui bundle, which hydrates the mount point, so the block is inert unless the site uses a docs-ui build that includes the explorer. This is the same "macro emits container, docs-ui hydrates it" handshake used by the Redpanda Connect component metadata block.
+
+Until the explorer module replaces the container's contents, the fallback paragraph is visible. It is ordinary markup rather than `<noscript>` on purpose: the failure readers are most likely to hit is JavaScript running normally on a site whose UI bundle has no explorer module, and a browser hides `<noscript>` in that case, leaving a zero-height blank space with no explanation.
+
+The page's component version (`page-version`, falling back to `page-component-version`) is stamped onto the mount point as `data-version` so the UI can load the engine build that matches the doc version. If neither attribute is set, `data-version` is omitted.
+
+Antora derives both attributes from the component version and locks them, so a page header cannot set them: an unversioned component (`version: ~`, which is what this repo's preview site uses) emits no `data-version`, and docs-ui falls back to its own version detection.
+
+=== Mount contract
+
+docs-ui must hydrate on the `data-iceberg-explorer` attribute (`[data-iceberg-explorer]`), never on a class name that matches the block name.
+
+Asciidoctor turns an unrecognized block style into a CSS class. A site that uses `[iceberg-explorer]` but whose playbook does not register this macro still publishes `<div class="openblock iceberg-explorer">`, with the author's JSON body dumped onto the page as a code listing. If the explorer module hydrated on `.iceberg-explorer`, that accident would render as a working-looking explorer filled with built-in sample data, the author's defaults silently discarded, and no error anywhere to trace it back to the missing playbook entry.
+
+Only this macro can emit a data attribute, so:
+
+* `data-iceberg-explorer` is the mount contract, and its value is the contract version (`1` today). Bump it only if the emitted attributes change shape.
+* `iceberg-explorer-mount` is a styling hook, not a mount signal.
+
+The constants are exported (`MOUNT_ATTRIBUTE`, `MOUNT_CONTRACT_VERSION`, `MOUNT_CLASS`, `MOUNT_SELECTOR`) so docs-ui and the tests can assert against one definition.
+
+=== Usage
+
+```asciidoc
+[iceberg-explorer]
+--
+--
+```
+
+Set the initial configuration with the `config` attribute:
+
+```asciidoc
+[iceberg-explorer,config="key:mode=binary;value:mode=binary"]
+--
+--
+```
+
+Or pass a JSON object as the block body to supply author-defined defaults:
+
+```asciidoc
+[iceberg-explorer]
+----
+{
+  "config": "value:mode=schema_latest"
+}
+----
+```
+
+The explorer module reads only the `config` key and renders its own sample schema and record. Other keys are forwarded verbatim in `data-defaults` and ignored, so do not document author-supplied schemas or records as supported until docs-ui reads them.
+
+The JSON is attribute-escaped and emitted as `data-defaults`. The body must be a JSON *object*: `JSON.parse()` also accepts scalars and arrays, and docs-ui reads keys off the parsed value, so a bare `123` is as unusable as a syntax error. If the body is not a JSON object, the macro logs a warning that names the page, omits `data-defaults`, and still renders the mount point.
+
+The block accepts an open (`--`), listing (`----`), literal, or pass body. It is not registered for the paragraph context, because the processor replaces the block with the mount point: registering paragraphs would delete the prose under a stray `[iceberg-explorer]` line from the published page.
+
+|===
+| Attribute | Description
+
+| `config`
+| Initial configuration string. Emitted as `data-config`. Falls back to the `config` key of the JSON body.
+
+| `height`
+| Minimum height for the container, emitted as an inline `min-height` style. A bare number is treated as pixels (`height=400` becomes `min-height:400px`). Otherwise the value must be a CSS length in `px`, `rem`, `em`, `vh`, `vw`, or `%`; any other value is rejected with a warning rather than interpolated into the style attribute.
+
+| `engine-base`
+| Optional base location for the translation engine build, emitted as `data-engine-base`. It must be a root-relative path on the docs site, such as `/_/engine/26.2`, because docs-ui loads a script from it. Any other value (an absolute or protocol-relative URL, a relative path, backslashes, or control characters) is ignored with a build warning. docs-ui falls back to its own default when this is absent, so set it only to pin a specific engine build.
+|===
+
+=== Registration
+
+[,yaml]
+----
+asciidoc:
+  extensions:
+    - '@redpanda-data/docs-extensions-and-macros/macros/iceberg-explorer'
+----
+
+=== docs-ui dependency
+
+This block is half of a two-repo handshake and does nothing on its own. The explorer UI and its translation engine ship in docs-ui, so the block requires a docs-ui release that includes the explorer module. On a site built with a bundle that lacks the module, the block renders the container and its fallback paragraph, nothing more.
+
+Order of operations before an author uses the block on a published page:
+
+. Merge and publish this package, so consumers can resolve the macro.
+. Release a docs-ui bundle that includes the explorer module, with hydration keyed on `[data-iceberg-explorer]` (see <<Mount contract>>).
+. Add the macro to each consuming playbook's `asciidoc.extensions` (`redpanda-data/docs`, `cloud-docs`). Registering it in this repo's `local-antora-playbook.yml` covers only this repo's preview site.
+
+Until step 2 lands, a page that uses the block shows the fallback paragraph rather than an explorer. That is deliberate: it is visible, so a missing or outdated UI bundle looks broken rather than looking like a page with nothing on it.
+
 == components_by_category
 
 This macro generates a tabbed interface to display Redpanda Connect components by category.

package/macros/badge.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { escapeHtml } = require('../extension-utils/html-utils');
+
 /**
  * Build the HTML for a badge.
  *
@@ -34,12 +36,7 @@ function buildBadgeHtml ({ label, size, tooltip } = {}) {
   // 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 className = `badge--${escapeAttr(text.toLowerCase().replace(/\s+/g, '-'))}`;
+  const className = `badge--${escapeHtml(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
@@ -49,12 +46,12 @@ function buildBadgeHtml ({ label, size, tooltip } = {}) {
     ? DEFAULT_TOOLTIPS[labelKey]
     : undefined;
   const hoverText = tooltip || defaultTooltip;
-  const tooltipAttr = hoverText ? ` data-tooltip="${escapeAttr(hoverText)}"` : '';
+  const tooltipAttr = hoverText ? ` data-tooltip="${escapeHtml(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 ? escapeAttr(text) : `(${escapeAttr(text)})`;
+  const renderedLabel = isLarge ? escapeHtml(text) : `(${escapeHtml(text)})`;
 
   return `<span class="badge ${className} ${sizeClass}"${tooltipAttr}>${renderedLabel}</span>`;
 }

package/macros/enterprise.js

@@ -69,6 +69,7 @@
  */
 
 const yaml = require('js-yaml')
+const { escapeHtml } = require('../extension-utils/html-utils')
 const semver = require('semver')
 const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
 const { isAttributeSet } = require('./prop')
@@ -545,11 +546,7 @@ function buildEnterpriseContent ({ feature, text, xref, url, tooltip, licensingP
   // 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, '&')
-    .replace(/"/g, '"')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
+  const escapedTooltip = escapeHtml(tooltipText)
   const tooltipHtml = tooltipAttr ? ` ${tooltipAttr}="${escapedTooltip}"` : ''
   let inner = display
   if (links) {

package/macros/glossary.js

@@ -3,22 +3,12 @@
 const $glossaryContexts = Symbol('$glossaryContexts')
 const { posix: path } = require('path')
 const logger = require('@antora/logger')('glossary-macro')
+const { escapeHtml } = require('../extension-utils/html-utils')
 
 // Backtick-monospace in hover-text. The unconstrained (double-backtick) form is
 // matched first, otherwise it leaves a stray delimiter on each side.
 const MONOSPACE_RX = /``([^`]+)``|`([^`]+)`/g
 
-// Escape for interpolation into a double-quoted HTML attribute. Same four
-// replacements, in the same order, as badge.js and enterprise.js; `&` has to go
-// first or it re-escapes the entities the later passes introduce.
-function escapeAttr (value) {
-  return String(value)
-    .replace(/&/g, '&')
-    .replace(/"/g, '"')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-}
-
 // Only a data-* tooltip is read by a JS tooltip library that renders it as HTML;
 // the native title attribute is always plain text. Shared with the
 // glossary-tooltip validation below so the two cannot drift apart.
@@ -45,14 +35,14 @@ function tooltipRendersHtml (tooltipAttr) {
 // file's raw :hover-text: value -- so it is escaped once rather than twice and
 // its markup survives to the reader instead of being shown as literal tags.
 function formatTooltipDefinition (text, tooltipAttr, definitionIsHtml) {
-  if (!tooltipRendersHtml(tooltipAttr)) return escapeAttr(text)
+  if (!tooltipRendersHtml(tooltipAttr)) return escapeHtml(text)
   if (definitionIsHtml) {
     // Already HTML, so one pass is right: the attribute decode hands the markup
     // back intact for innerHTML to render, and a quote in the text still cannot
     // terminate the attribute early.
-    return escapeAttr(text)
+    return escapeHtml(text)
   }
-  return escapeAttr(escapeAttr(text)).replace(
+  return escapeHtml(escapeHtml(text)).replace(
     MONOSPACE_RX,
     (match, unconstrained, constrained) =>
       `<code>${unconstrained !== undefined ? unconstrained : constrained}</code>`

package/macros/iceberg-explorer.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const { escapeHtml } = require('../extension-utils/html-utils');
+// Same logger as the other macros (#283): warnings land in Antora's log with
+// a level Antora can fail on, instead of bypassing it through console.warn.
+const logger = require('@antora/logger')('iceberg-explorer-macro');
+
+/**
+ * Iceberg Mode Explorer block.
+ *
+ * Registers an `[iceberg-explorer]` AsciiDoc block that emits a lightweight,
+ * version-aware mount point. The interactive tool itself (Ace editors,
+ * controls, rendering) and its translation engine live in the docs-ui bundle;
+ * a docs-ui JS module hydrates every element carrying the mount attribute
+ * (`MOUNT_SELECTOR` below).
+ *
+ * This mirrors the "macro emits container -> docs-ui JS hydrates" handshake
+ * used by the component metadata block in `rp-connect-components.js` +
+ * `docs-ui/src/js/24-move-connector-metadata.js`.
+ *
+ * MOUNT CONTRACT. docs-ui must hydrate on the `data-iceberg-explorer`
+ * attribute, never on a class name that matches the block name. Asciidoctor
+ * turns an unrecognized block style into a CSS class, so a page that uses
+ * `[iceberg-explorer]` in a site whose playbook forgot to register this macro
+ * still renders `<div class="openblock iceberg-explorer">`. Hydrating on
+ * `.iceberg-explorer` would dress that accident up as a working explorer
+ * showing built-in sample data while the author's JSON body was discarded, with
+ * no error anywhere. Only this macro can emit a data attribute, so the
+ * attribute is the contract and the class is for styling only.
+ *
+ * Authoring:
+ *
+ *   [iceberg-explorer]
+ *   --
+ *   --
+ *
+ * or with author-supplied defaults (JSON) as the block body:
+ *
+ *   [iceberg-explorer]
+ *   ----
+ *   {
+ *     "config": "key:mode=binary;value:mode=schema_id_prefix,layout=flat;headers:value_type=binary"
+ *   }
+ *   ----
+ *
+ * The explorer module reads only the "config" key (docs-ui
+ * src/js/27-iceberg-explorer.js), rendering its own sample schema and record.
+ * Any other key is forwarded verbatim in `data-defaults` and ignored today, so
+ * do not advertise author-supplied schemas or records as supported.
+ *
+ * The block reads the page's component version and stamps it onto the mount
+ * point so the UI can fetch the engine build that matches the doc version.
+ *
+ * @param {Registry} registry - The Antora/Asciidoctor extension registry.
+ * @param {Object} context - The Antora context (unused today; kept for parity
+ *   with the other macros and for future content-catalog resolution).
+ */
+
+// Mount contract shared with docs-ui. Exported so both sides and the tests
+// reference one definition instead of a hard-coded string in three places.
+const MOUNT_ATTRIBUTE = 'data-iceberg-explorer';
+// Bumped only if the emitted attributes change shape, so a docs-ui build can
+// refuse a mount point it does not understand.
+const MOUNT_CONTRACT_VERSION = '1';
+// Styling hook only. Deliberately NOT the block name: see MOUNT CONTRACT above.
+const MOUNT_CLASS = 'iceberg-explorer-mount';
+const MOUNT_SELECTOR = `[${MOUNT_ATTRIBUTE}]`;
+
+module.exports.register = function (registry, context) {
+  // Support both calling conventions:
+  //  - Antora passes a registry as the first argument; it exposes `.block()`
+  //    directly, so register on it.
+  //  - Some preview harnesses (e.g. docs-ui's build-preview-pages) call
+  //    `register.call(Asciidoctor.Extensions)` with the Extensions module as
+  //    `this` and no arguments. That module exposes `.register(fn)` (not
+  //    `.block()`); inside `fn`, `this` is a registry with `.block()`.
+  const target = registry || this;
+  if (typeof target.block === 'function') {
+    defineBlock(target);
+  } else if (typeof target.register === 'function') {
+    target.register(function () { defineBlock(this); });
+  } else {
+    throw new Error('iceberg-explorer: no usable Asciidoctor registry provided');
+  }
+};
+
+function defineBlock (registry) {
+  registry.block(function () {
+    const self = this;
+    self.named('iceberg-explorer');
+    // Accept an empty open block (`--`) or a listing/literal/pass block whose
+    // body carries author-supplied JSON defaults. `paragraph` is deliberately
+    // absent: the processor discards the body, so registering the paragraph
+    // context made `[iceberg-explorer]` above ordinary prose delete that
+    // paragraph from the published page.
+    self.onContext(['open', 'listing', 'literal', 'pass']);
+    self.process((parent, reader, attrs) => {
+      const attributes = parent.getDocument().getAttributes();
+      // Name the page in every warning. Antora sets page-relative-src-path
+      // (the convention rp-connect-components.js follows); plain Asciidoctor
+      // runs only have docfile.
+      const page =
+        attributes['page-relative-src-path'] ||
+        attributes['docfile'] ||
+        'unknown page';
+      const warn = (message) => {
+        logger.warn(`${page}: ${message}`);
+      };
+
+      // Author-supplied defaults (optional). Validate that the body is a JSON
+      // object so a typo surfaces at build time rather than silently shipping
+      // bad data. docs-ui reads keys off the parsed value, so a scalar or an
+      // array is as unusable as a syntax error, and JSON.parse accepts both.
+      let defaults = null;
+      const body = reader.getLines().join('\n').trim();
+      if (body) {
+        let parsed;
+        let valid = false;
+        try {
+          parsed = JSON.parse(body);
+          valid = true;
+        } catch (err) {
+          warn(
+            `block body is not valid JSON (${err.message}). ` +
+            'Rendering the explorer with built-in defaults instead.'
+          );
+        }
+        if (valid) {
+          if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            warn(
+              `block body must be a JSON object with a "config" key, not ${describeJson(parsed)}. ` +
+              'Rendering the explorer with built-in defaults instead.'
+            );
+          } else {
+            defaults = parsed;
+          }
+        }
+      }
+
+      // Doc version drives which engine build the UI loads. `page-version` is
+      // the short component version (for example, "26.2"); fall back to the
+      // component version attribute if present.
+      const version =
+        attributes['page-version'] ||
+        attributes['page-component-version'] ||
+        '';
+
+      // Optional named attributes let an author pin behavior without a body.
+      // `config` sets the initial DSL string; `height` overrides the min
+      // height; `engine-base` overrides where docs-ui fetches the engine from.
+      const initialConfig = attrs.config || (defaults && defaults.config) || '';
+      const height = cssLength(attrs.height, warn);
+      const engineBase = rootRelativePath(attrs['engine-base'], warn);
+
+      const dataDefaults = defaults
+        ? escapeHtml(JSON.stringify(defaults))
+        : '';
+      const dataConfig = initialConfig ? escapeHtml(initialConfig) : '';
+      const styleAttr = height ? ` style="min-height:${height}"` : '';
+      const versionAttr = version ? ` data-version="${escapeHtml(version)}"` : '';
+      const engineAttr = engineBase ? ` data-engine-base="${escapeHtml(engineBase)}"` : '';
+
+      // The container is a mount point only; docs-ui replaces its contents on
+      // hydration. Until then the fallback paragraph is visible, so the two
+      // ways this can fail (JS disabled, or a docs-ui build without the
+      // explorer module) both show a message instead of a 0px-tall void. It is
+      // plain markup, not <noscript>, precisely because the common failure is
+      // JS running fine with the module missing, which <noscript> hides.
+      const html = `
+<div class="${MOUNT_CLASS}" ${MOUNT_ATTRIBUTE}="${MOUNT_CONTRACT_VERSION}"${versionAttr}${engineAttr}${dataConfig ? ` data-config="${dataConfig}"` : ''}${dataDefaults ? ` data-defaults="${dataDefaults}"` : ''}${styleAttr}>
+  <p class="iceberg-explorer-fallback">Interactive Iceberg Mode Explorer. If this text is still here, the explorer could not load: it needs JavaScript and a docs-ui build that includes the explorer module. See the Iceberg topic configuration reference for the equivalent settings.</p>
+</div>`;
+
+      return self.createBlock(parent, 'pass', html);
+    });
+  });
+};
+
+/**
+ * Describe a parsed-but-unusable JSON body for the build warning.
+ * @param {*} value
+ * @returns {string}
+ */
+function describeJson (value) {
+  if (Array.isArray(value)) return 'an array';
+  if (value === null) return 'null';
+  return `a ${typeof value}`;
+}
+
+/**
+ * Validate the `height` attribute as a CSS length. A bare number is the natural
+ * thing to write and produces `min-height:400`, which browsers drop, so accept
+ * it and add `px`. Anything else is rejected rather than interpolated: the value
+ * lands inside a style attribute, where `1px;position:fixed;inset:0` would turn
+ * a doc page into a full-viewport overlay.
+ * @param {string} raw
+ * @param {function(string): void} warn
+ * @returns {string} A safe CSS length, or '' to omit the style attribute.
+ */
+function cssLength (raw, warn) {
+  if (!raw) return '';
+  const value = String(raw).trim();
+  if (/^\d+$/.test(value)) return `${value}px`;
+  if (/^\d+(\.\d+)?(px|rem|em|vh|vw|%)$/.test(value)) return value;
+  warn(
+    `height="${value}" is not a CSS length (for example, 400, 400px, 30rem, 60vh). Ignoring it.`
+  );
+  return '';
+}
+
+/**
+ * Validate the `engine-base` attribute as a same-origin, root-relative path.
+ * docs-ui loads `<engine-base>/iceberg-engine-<version>.js` as a script, so any
+ * other value would let page source run another origin's JavaScript on the docs
+ * site. Escaping stops HTML injection but does not make a URL trustworthy, so
+ * reject schemes, protocol-relative paths (`//host`), backslashes (which
+ * browsers treat as `/`), whitespace, and raw or percent-encoded control
+ * characters.
+ * @param {string} raw
+ * @param {function(string): void} warn
+ * @returns {string} A safe root-relative path, or '' to use the docs-ui default.
+ */
+function rootRelativePath (raw, warn) {
+  if (!raw) return '';
+  const value = String(raw);
+  const safe =
+    /^\/(?![\/\\])/.test(value) &&
+    !/[\\\s\x00-\x1f\x7f]/.test(value) &&
+    !/%(?:[01][0-9a-f]|7f|5c)/i.test(value);
+  if (safe) return value;
+  warn(
+    `engine-base="${value}" is not a root-relative path on this site (for example, /_/engine/26.2). ` +
+    'Ignoring it, so docs-ui loads the engine from its default location.'
+  );
+  return '';
+}
+
+module.exports.MOUNT_ATTRIBUTE = MOUNT_ATTRIBUTE;
+module.exports.MOUNT_CONTRACT_VERSION = MOUNT_CONTRACT_VERSION;
+module.exports.MOUNT_CLASS = MOUNT_CLASS;
+module.exports.MOUNT_SELECTOR = MOUNT_SELECTOR;
+module.exports.rootRelativePath = rootRelativePath;

package/macros/prop.js

@@ -91,6 +91,7 @@
  */
 
 const semver = require('semver')
+const { escapeHtml } = require('../extension-utils/html-utils')
 const logger = require('@antora/logger')('prop-macro')
 
 const $propertyRegistry = Symbol('$propertyRegistry')
@@ -867,19 +868,8 @@ function buildPropContent ({ name, text, link, page, scope, role, helmPath = fal
   // attribute, docUrl from a page's published URL, and name from a dataset
   // key: an unescaped quote in any of them ends the attribute early and the
   // remainder becomes stray attributes on every marked property in the build.
-  const docAttr = docUrl ? ` data-doc-url="${escapeAttribute(docUrl)}"` : ''
-  return `<code class="${escapeAttribute(role)}" data-property-name="${escapeAttribute(name)}"${docAttr}>${inner}</code>`
-}
-
-/**
- * Escape a value for use inside a double-quoted HTML attribute.
- */
-function escapeAttribute (value) {
-  return String(value === undefined || value === null ? '' : value)
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
+  const docAttr = docUrl ? ` data-doc-url="${escapeHtml(docUrl)}"` : ''
+  return `<code class="${escapeHtml(role)}" data-property-name="${escapeHtml(name)}"${docAttr}>${inner}</code>`
 }
 
 function propInlineMacro (config) {