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

package/cli-utils/antora-utils.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Attempts to locate and parse `antora.yml` in the current working directory.
+ *
+ * @returns {Object|undefined} The parsed YAML as a JavaScript object, or undefined if not found or on error.
+ */
+function loadAntoraConfig() {
+  const antoraPath = path.join(process.cwd(), 'antora.yml');
+  if (!fs.existsSync(antoraPath)) {
+    // No antora.yml in project root
+    return undefined;
+  }
+
+  try {
+    const fileContents = fs.readFileSync(antoraPath, 'utf8');
+    const config = yaml.load(fileContents);
+    if (typeof config !== 'object' || config === null) {
+      console.error('Warning: antora.yml parsed to a non‐object value.');
+      return undefined;
+    }
+    return config;
+  } catch (err) {
+    console.error(`Error reading/parsing antora.yml: ${err.message}`);
+    return undefined;
+  }
+}
+
+/**
+ * Safely retrieves a nested value from the Antora configuration, given a "dot path".
+ *
+ * Example usage:
+ *   const latestVersion = getAntoraValue('asciidoc.attributes.latest-connect-version');
+ *
+ * @param {string} keyPath
+ *   A dot-separated path into the Antora object (e.g. "asciidoc.attributes.foo").
+ * @returns {*}
+ *   The value at that path, or undefined if the file is missing or the key does not exist.
+ */
+function getAntoraValue(keyPath) {
+  const config = loadAntoraConfig();
+  if (!config) {
+    return undefined;
+  }
+
+  // Split on dots, but ignore empty segments
+  const segments = keyPath.split('.').filter(Boolean);
+  let cursor = config;
+
+  for (const seg of segments) {
+    if (cursor && typeof cursor === 'object' && seg in cursor) {
+      cursor = cursor[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return cursor;
+}
+
+/**
+ * Safely sets a nested value in the Antora configuration, given a "dot path".
+ * If the file or path does not exist, it will create intermediate objects as needed.
+ * After setting the value, writes the updated YAML back to `antora.yml`.
+ *
+ * @param {string} keyPath
+ *   A dot-separated path to set (e.g. "asciidoc.attributes.latest-connect-version").
+ * @param {*} newValue
+ *   The new value to assign at that path.
+ * @returns {boolean}
+ *   True if it succeeded, false otherwise.
+ */
+function setAntoraValue(keyPath, newValue) {
+  const antoraPath = path.join(process.cwd(), 'antora.yml');
+  if (!fs.existsSync(antoraPath)) {
+    console.error('Cannot update antora.yml: file not found in project root.');
+    return false;
+  }
+
+  let config;
+  try {
+    const fileContents = fs.readFileSync(antoraPath, 'utf8');
+    config = yaml.load(fileContents) || {};
+    if (typeof config !== 'object' || config === null) {
+      config = {};
+    }
+  } catch (err) {
+    console.error(`Error reading/parsing antora.yml: ${err.message}`);
+    return false;
+  }
+
+  // Traverse/construct nested objects
+  const segments = keyPath.split('.').filter(Boolean);
+  let cursor = config;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (i === segments.length - 1) {
+      // Last segment: assign
+      cursor[seg] = newValue;
+    } else {
+      // Intermediate: ensure object
+      if (!(seg in cursor) || typeof cursor[seg] !== 'object' || cursor[seg] === null) {
+        cursor[seg] = {};
+      }
+      cursor = cursor[seg];
+    }
+  }
+
+  // Serialize back to YAML and write
+  try {
+    const newYaml = yaml.dump(config, { lineWidth: 120 });
+    fs.writeFileSync(antoraPath, newYaml, 'utf8');
+    return true;
+  } catch (err) {
+    console.error(`Error writing antora.yml: ${err.message}`);
+    return false;
+  }
+}
+
+module.exports = {
+  loadAntoraConfig,
+  getAntoraValue,
+  setAntoraValue,
+};

package/cli-utils/convert-doc-links.js

@@ -0,0 +1,58 @@
+const { URL } = require('url');
+
+/**
+ * Converts a docs.redpanda.com URL, optionally suffixed with a label in brackets, into an Antora xref resource ID string.
+ *
+ * If the input includes a label in square brackets (e.g., `[Label]`), the label is preserved and appended to the resulting xref.
+ *
+ * @param {string} input - A docs.redpanda.com URL, optionally followed by a label in square brackets.
+ * @returns {string} The corresponding Antora xref resource ID, with the label preserved if present.
+ *
+ * @throws {Error} If the input is not a valid URL or does not belong to docs.redpanda.com.
+ */
+function urlToXref(input) {
+  // Peel off an optional “[label]”
+  let urlPart  = input;
+  let label    = '';
+  const mLabel = input.match(/^(.*)\[([^\]]+)\]$/);
+  if (mLabel) {
+    urlPart = mLabel[1];
+    label   = mLabel[2];
+  }
+
+  //Parse & validate
+  let url;
+  try {
+    url = new URL(urlPart);
+  } catch {
+    throw new Error(`Invalid URL: ${input}`);
+  }
+  if (!/docs\.redpanda\.com$/.test(url.hostname)) {
+    throw new Error(`Not a docs.redpanda.com URL: ${input}`);
+  }
+
+  // Strip any leading “/docs”, “/docs/vX.Y”, “/docs/current”, “/vX.Y” or “/current”
+  let p = url.pathname.replace(
+    /^\/(?:docs(?:\/(?:v?\d+\.\d+|current))?|v?\d+\.\d+|current)\/?/,
+    ''
+  );
+  // Drop trailing slash
+  p = p.replace(/\/$/, '');
+  const segments = p.split('/').filter(Boolean);
+
+  // Build module + path + .adoc
+  let xref;
+  if (segments.length === 0) {
+    xref = 'xref:index.adoc';
+  } else {
+    const moduleName = segments.shift();
+    const pagePath   = segments.join('/');
+    const fileName   = (pagePath || moduleName) + '.adoc';
+    xref = `xref:${moduleName}:${fileName}`;
+  }
+
+  // Re-attach label if there was one
+  return label ? `${xref}[${label}]` : xref;
+}
+
+module.exports = { urlToXref };

package/cli-utils/generate-cluster-docs.sh

@@ -73,7 +73,7 @@ else
     "$TAG"
 fi
 
-echo "✅ Redpanda cluster docs generated successfully!"
+echo "✅ $MODE docs generated successfully!"
 
 # Tear down the cluster
 cd "$SCRIPT_DIR"/../docker-compose

package/cli-utils/self-managed-docs-branch.js

@@ -0,0 +1,91 @@
+const https = require('https');
+const yaml = require('js-yaml');
+const { spawnSync } = require('child_process');
+
+/**
+ * Retrieves the current Self-Managed documentation version from the remote antora.yml file.
+ *
+ * @returns {Promise<string>} Resolves with the version string (e.g., "25.1").
+ *
+ * @throws {Error} If the antora.yml file cannot be fetched, parsed, or if the version field is missing.
+ */
+function fetchRemoteAntoraVersion() {
+  const url = 'https://raw.githubusercontent.com/redpanda-data/docs/main/antora.yml'
+  return new Promise((resolve, reject) => {
+    https.get(url, res => {
+      if (res.statusCode !== 200) {
+        return reject(new Error(`Failed to fetch antora.yml: ${res.statusCode}`))
+      }
+      let body = ''
+      res.on('data', chunk => (body += chunk))
+      res.on('end', () => {
+        try {
+          const cfg = yaml.load(body)
+          if (cfg.version == null) {
+            throw new Error('version field missing')
+          }
+          const version = String(cfg.version).trim()
+          resolve(version)
+        } catch (err) {
+          reject(err)
+        }
+      })
+    }).on('error', reject)
+  })
+}
+
+/**
+ * Determines the appropriate documentation branch for a given operator tag based on the remote Antora version.
+ *
+ * Normalizes the input tag, extracts the major.minor version, and applies version-specific logic to select the correct branch. Verifies that the chosen branch exists in the remote repository.
+ *
+ * @param {string} operatorTag - The operator tag to evaluate (e.g., "operator/v25.1.2" or "v25.1.2").
+ * @returns {Promise<string>} The name of the documentation branch to use.
+ *
+ * @throws {Error} If the tag cannot be parsed or if the determined branch does not exist in the remote repository.
+ */
+async function determineDocsBranch(operatorTag) {
+  // Strip any "operator/" prefix
+  const TAG = operatorTag.replace(/^(?:operator|release)\//, '')
+  // Pull in the remote Antora version
+  const ANTORA = await fetchRemoteAntoraVersion()
+  // Extract v<major>.<minor>
+  const mm = TAG.match(/^v(\d+\.\d+)/)
+  const filtered = mm ? `v${mm[1]}` : null
+
+  if (!filtered) {
+    throw new Error(`Could not parse major.minor from ${TAG}`)
+  }
+  // We started versioning the operator in line with Redpanda core versions. But when v2.4.x was the latest version, the docs were still on 25.1 and v25.1.x of the operator was still in beta. So we need to handle this special case.
+  let branch
+  if (filtered === 'v2.4') {
+    if (ANTORA === '25.1') {
+      branch = 'main'
+    } else {
+      branch = 'v/24.3'
+    }
+  // For all other versions use the v<major>.<minor> branch unless it is the current version, in which case we use 'main'.
+  } else if (filtered === `v${ANTORA}`) {
+    branch = 'main'
+  } else {
+    branch = `v/${filtered.slice(1)}`
+  }
+
+  // Verify branch exists
+  const repo = 'https://github.com/redpanda-data/docs.git'
+  const ref  = `refs/heads/${branch}`
+  const ok = spawnSync('git', ['ls-remote', '--exit-code', '--heads', repo, ref], {
+    stdio: 'ignore'
+  }).status === 0
+
+  if (!ok) {
+    throw new Error(`Docs branch ${branch} not found in ${repo}`)
+  }
+
+  return branch
+}
+
+module.exports = {
+  fetchRemoteAntoraVersion,
+  determineDocsBranch
+}

package/cli-utils/start-cluster.sh

@@ -20,12 +20,22 @@ if [[ "$TAG" != "latest" ]]; then
   MAJOR_MINOR="$(echo "$TAG" | sed -E 's/^v?([0-9]+\.[0-9]+).*$/\1/')"
 fi
 
+# Conditionally override quickstart dir for >= 25.1
+if [[ "$MAJOR_MINOR" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  major="${BASH_REMATCH[1]}"
+  minor="${BASH_REMATCH[2]}"
+
+  if (( major > 25 )) || (( major == 25 && minor >= 1 )); then
+    QUICKSTART_DIR="$PACKAGE_ROOT/docker-compose/25.1"
+  fi
+fi
+
 # Fetch quickstart into package root if needed
 if [[ ! -d "$QUICKSTART_DIR" ]]; then
   echo "📥 Fetching Redpanda quickstart for ${MAJOR_MINOR}…"
   if [[ "$TAG" == "latest" ]]; then
-	  curl -sSLf --retry 3 https://docs.redpanda.com/redpanda-quickstart.tar.gz \
-	  | tar -C "$PACKAGE_ROOT" -xzf -
+    curl -sSLf --retry 3 https://docs.redpanda.com/redpanda-quickstart.tar.gz \
+      | tar -C "$PACKAGE_ROOT" -xzf -
   else
     curl -sSLf --retry 3 "https://docs.redpanda.com/${MAJOR_MINOR}-redpanda-quickstart.tar.gz" \
       | tar -C "$PACKAGE_ROOT" -xzf -

package/docker-compose/25.1/bootstrap.yml

@@ -0,0 +1,67 @@
+# =================================================================
+# This file defines initial cluster properties for a Redpanda cluster.
+# Some of these settings are intended for quickstart development and evaluation
+# and are not suitable for production environments.
+#
+# For more information on bootstrap files, see:
+# https://docs.redpanda.com/current/deploy/deployment-option/self-hosted/manual/production/production-deployment/#configure-a-bootstrap-file
+# =================================================================
+
+#
+# Enable SASL authentication for the Kafka and Admin APIs.
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#admin_api_require_auth
+admin_api_require_auth: true
+# At least one superuser is required to be able to create other SASL users
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#superusers
+superusers:
+  - superuser
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#enable_sasl
+enable_sasl: true
+# Allow topics to be created on first access.
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#auto_create_topics_enabled
+auto_create_topics_enabled: true
+# Enable data transforms.
+# https://docs.redpanda.com/current/develop/data-transforms/how-transforms-work/
+data_transforms_enabled: true
+# Enable audit logging (enterprise feature).
+# https://docs.redpanda.com/current/manage/audit-logging/
+audit_enabled: true
+# Enable Tiered Storage (enterprise feature).
+# https://docs.redpanda.com/current/manage/tiered-storage/
+cloud_storage_enabled: true
+cloud_storage_region: local
+cloud_storage_access_key: minio
+cloud_storage_secret_key: redpandaTieredStorage7
+cloud_storage_api_endpoint: minio
+cloud_storage_api_endpoint_port: 9000
+cloud_storage_disable_tls: true
+cloud_storage_bucket: redpanda
+cloud_storage_enable_remote_write: true
+cloud_storage_enable_remote_read: true
+# Forces segments to be uploaded to Tiered Storage faster for the purposes of the quickstart
+# https://docs.redpanda.com/current/reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec
+cloud_storage_segment_max_upload_interval_sec: 60
+# Continuous Data Balancing (enterprise feature) continuously monitors your node and rack availability and disk usage. This enables self-healing clusters that dynamically balance partitions, ensuring smooth operations and optimal cluster performance.
+# https://docs.redpanda.com/current/manage/cluster-maintenance/continuous-data-balancing/
+partition_autobalancing_mode: continuous
+# Enable Redpanda to collect consumer group metrics.
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#enable_consumer_group_metrics
+enable_consumer_group_metrics:
+  - "group"
+  - "partition"
+  - "consumer_lag"
+# Lower the interval for the autogeneration of consumer group metrics.
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#consumer_group_lag_collection_interval_sec
+consumer_group_lag_collection_interval_sec: 60
+# Enable Redpanda to collect host metrics.
+# https://docs.redpanda.com/current/reference/properties/cluster-properties/#enable_host_metrics
+enable_host_metrics: true
+# Enable for Iceberg metrics
+iceberg_enabled: true
+# Set up Iceberg REST catalog configuration
+iceberg_catalog_type: rest
+iceberg_rest_catalog_endpoint: http://catalog:8181
+# Credentials are required, but the catalog ignores them
+iceberg_rest_catalog_client_id: catalog
+iceberg_rest_catalog_client_secret: catalog123
+iceberg_catalog_commit_interval_ms: 5000