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

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/generate-cluster-docs.sh

@@ -1,23 +1,34 @@
 #!/usr/bin/env bash
 set -euo pipefail
+IFS=$'\n\t'
 
-# Check if Docker is installed and running
+###############################################################################
+# Pre-flight: Ensure Docker is available and running
+###############################################################################
 if ! command -v docker &> /dev/null; then
   echo "❌ Docker is not installed or not in PATH. Please install Docker to continue."
   exit 1
 fi
 
-# Check if Docker daemon is running
 if ! docker info &> /dev/null; then
   echo "❌ Docker daemon is not running. Please start Docker to continue."
   exit 1
 fi
 
-# Remember where we started so we can always come back
-ORIGINAL_PWD="$(pwd)"
+###############################################################################
+# Load overrides from an optional .env file in the current directory
+###############################################################################
+if [[ -f .env ]]; then
+  # shellcheck disable=SC2046
+  export $(grep -Ev '^#' .env | xargs)
+fi
 
-# All "cli-utils…" calls should be relative to this script’s dir
+###############################################################################
+# Environment setup
+###############################################################################
+ORIGINAL_PWD="$(pwd)"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_NAME="${PROJECT_NAME:-redpanda_quickstart}"
 
 MODE="${1:-metrics}"
 TAG="${2:-latest}"
@@ -25,16 +36,15 @@ DOCKER_REPO="${3:-redpanda}"
 CONSOLE_TAG="${4:-latest}"
 CONSOLE_REPO="${5:-console}"
 
-# if it's an RC tag, switch Docker repo
+# Adjust Docker repo for release candidates
 shopt -s nocasematch
 if [[ "$TAG" =~ rc[0-9]+ ]]; then
   DOCKER_REPO="redpanda-unstable"
 fi
 shopt -u nocasematch
 
-if [[ "$TAG" == "latest" ]]; then
-  MAJOR_MINOR="latest"
-else
+MAJOR_MINOR="latest"
+if [[ "$TAG" != "latest" ]]; then
   MAJOR_MINOR="$(echo "$TAG" | sed -E 's/^v?([0-9]+\.[0-9]+).*$/\1/')"
 fi
 
@@ -43,41 +53,43 @@ export REDPANDA_DOCKER_REPO="$DOCKER_REPO"
 export REDPANDA_CONSOLE_VERSION="$CONSOLE_TAG"
 export REDPANDA_CONSOLE_DOCKER_REPO="$CONSOLE_REPO"
 
-# Start up the cluster
-"$SCRIPT_DIR"/start-cluster.sh "$TAG"
+###############################################################################
+# Start Redpanda cluster
+###############################################################################
+"$SCRIPT_DIR/start-cluster.sh" "$TAG"
 
-# Wait for it to settle
+# Wait for the cluster to settle
 if [[ "$MODE" == "metrics" ]]; then
-  echo "Waiting 300 seconds for metrics to be available…"
+  echo "⏳ Waiting 300 seconds for metrics to be available…"
   sleep 300
 else
-  echo "Waiting 30 seconds for cluster to be ready…"
+  echo "⏳ Waiting 30 seconds for cluster to be ready…"
   sleep 30
 fi
 
-# Go back to where we were
-cd "$ORIGINAL_PWD"
-
-# Ensure Python venv (always create under cli-utils/venv)
-"$SCRIPT_DIR"/python-venv.sh \
-  "$SCRIPT_DIR"/venv \
-  "$SCRIPT_DIR"/../tools/metrics/requirements.txt
+###############################################################################
+# Python virtual environment setup
+###############################################################################
+"$SCRIPT_DIR/python-venv.sh" \
+  "$SCRIPT_DIR/venv" \
+  "$SCRIPT_DIR/../tools/metrics/requirements.txt"
 
+###############################################################################
+# Run documentation generator
+###############################################################################
 if [[ "$MODE" == "metrics" ]]; then
-  "$SCRIPT_DIR"/venv/bin/python \
-    "$SCRIPT_DIR"/../tools/metrics/metrics.py \
-    "$TAG"
+  "$SCRIPT_DIR/venv/bin/python" \
+    "$SCRIPT_DIR/../tools/metrics/metrics.py" "$TAG"
 else
-  "$SCRIPT_DIR"/venv/bin/python \
-    "$SCRIPT_DIR"/../tools/gen-rpk-ascii.py \
-    "$TAG"
+  "$SCRIPT_DIR/venv/bin/python" \
+    "$SCRIPT_DIR/../tools/gen-rpk-ascii.py" "$TAG"
 fi
 
 echo "✅ $MODE docs generated successfully!"
 
 # Tear down the cluster
 cd "$SCRIPT_DIR"/../docker-compose
-docker compose down --volumes
+docker compose -p "$PROJECT_NAME" down --volumes
 
 # Return to the original directory
-cd "$ORIGINAL_PWD"
+cd "$ORIGINAL_PWD" || exit 1

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

@@ -56,7 +56,7 @@ async function determineDocsBranch(operatorTag) {
   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') {
@@ -64,6 +64,7 @@ async function determineDocsBranch(operatorTag) {
     } 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 {

package/cli-utils/start-cluster.sh

@@ -1,63 +1,103 @@
 #!/usr/bin/env bash
 set -euo pipefail
+IFS=$'\n\t'
 
-# Usage: start-cluster.sh <tag>
-TAG="${1:-latest}"
+###############################################################################
+# Set START_CLUSTER_LOG=/path/to/logfile to capture output
+###############################################################################
+if [[ -n "${START_CLUSTER_LOG:-}" ]]; then
+  exec > >(tee -a "$START_CLUSTER_LOG") 2>&1
+fi
 
-# Where this script lives (cli-utils)
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+###############################################################################
+# Prevent concurrent runs with a simple lockfile
+###############################################################################
+LOCKFILE="/tmp/start-cluster.lock"
+if [[ -e "$LOCKFILE" ]]; then
+  echo "❗ Another start-cluster.sh is already running. Remove $LOCKFILE if stale." >&2
+  exit 1
+fi
+trap 'rm -f "$LOCKFILE"' EXIT
+touch "$LOCKFILE"
 
-# One level up is the package root, where we expect docker‑compose/
-PACKAGE_ROOT="$(cd "$SCRIPT_DIR"/.. && pwd)"
-QUICKSTART_DIR="$PACKAGE_ROOT/docker-compose"
+###############################################################################
+# Input parameters and defaults
+###############################################################################
+TAG="${1:-${CLUSTER_TAG:-latest}}"
+PROJECT_NAME="${PROJECT_NAME:-redpanda_quickstart}"
 
-# Remember where the user called us from
+###############################################################################
+# Directory discovery
+###############################################################################
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+QUICKSTART_DIR="$PACKAGE_ROOT/docker-compose"
 CALLER_PWD="$(pwd)"
 
-# Default quickstart version
+###############################################################################
+# Determine major.minor for quickstart override
+###############################################################################
 MAJOR_MINOR="latest"
 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
+###############################################################################
+# Fetch quickstart bundle if missing
+###############################################################################
 if [[ ! -d "$QUICKSTART_DIR" ]]; then
   echo "📥 Fetching Redpanda quickstart for ${MAJOR_MINOR}…"
+  url="https://docs.redpanda.com"
   if [[ "$TAG" == "latest" ]]; then
-    curl -sSLf --retry 3 https://docs.redpanda.com/redpanda-quickstart.tar.gz \
-      | tar -C "$PACKAGE_ROOT" -xzf -
+    url="$url/redpanda-quickstart.tar.gz"
   else
-    curl -sSLf --retry 3 "https://docs.redpanda.com/${MAJOR_MINOR}-redpanda-quickstart.tar.gz" \
-      | tar -C "$PACKAGE_ROOT" -xzf -
-  fi
-
-  if [[ ! -d "$QUICKSTART_DIR" ]]; then
-    echo "❌ Expected '$QUICKSTART_DIR' but none was found after extraction."
-    exit 1
+    url="$url/${MAJOR_MINOR}-redpanda-quickstart.tar.gz"
   fi
+  curl -sSLf --retry 3 "$url" | tar -C "$PACKAGE_ROOT" -xzf -
+  [[ -d "$QUICKSTART_DIR" ]] || { echo "❌ Expected '$QUICKSTART_DIR' but none was found."; exit 1; }
 fi
 
-# Switch into the quickstart dir and (re)start the cluster
-cd "$QUICKSTART_DIR"
+###############################################################################
+# Move into compose directory and clean up existing cluster
+###############################################################################
+cd "$QUICKSTART_DIR" || { echo "❌ Cannot cd to '$QUICKSTART_DIR'"; exit 1; }
 
-if docker compose ps | grep -q Up; then
-  echo "🛑 Stopping existing cluster…"
-  docker compose down --volumes
+if docker compose -p "$PROJECT_NAME" ps -q | grep -q .; then
+  echo "🛑 Cleaning up existing cluster…"
+  docker compose -p "$PROJECT_NAME" down --volumes
+else
+  echo "No running containers to remove for project \"$PROJECT_NAME\"."
 fi
 
-echo "▶️  Starting Redpanda cluster…"
-docker compose up -d
+###############################################################################
+# Remove globally conflicting containers (dynamic list + legacy minio)
+###############################################################################
+services=$(docker compose -p "$PROJECT_NAME" config --services 2>/dev/null || true)
+services+=" minio"   # ensure legacy /minio container is handled
+
+for svc in $services; do
+  if docker ps -a --format '{{.Names}}' | grep -wq "$svc"; then
+    echo "🧹 Removing existing container: $svc"
+    docker rm -f "$svc"
+  fi
+done
+
+###############################################################################
+# Start cluster
+###############################################################################
+echo "▶️  Starting Redpanda cluster (version: ${TAG})…"
+docker compose -p "$PROJECT_NAME" up -d
 
-# Return to original directory
-cd "$CALLER_PWD"
+###############################################################################
+# Return to caller and report success
+###############################################################################
+cd "$CALLER_PWD" || exit 1
 echo "✅ Cluster is up (version: ${TAG})"

package/extensions/generate-rp-connect-info.js

@@ -82,14 +82,14 @@ module.exports.register = function ({ config }) {
   }
 
   /**
-   * Translates the parsed CSV data into our expected format.
-   * If "enterprise" is found in the `support` column, it is replaced with "certified" in the output.
+   * Transforms and enriches parsed CSV connector data with normalized fields and documentation URLs.
    *
-   * @param {object} parsedData - The CSV data parsed into an object.
-   * @param {array} pages - The list of pages to map the URLs (used for enrichment with URLs).
-   * @param {object} logger - The logger used for error handling.
+   * Each row is trimmed, mapped to expected output fields, and enriched with documentation URLs for Redpanda Connect and Cloud components if available. The `support` field is normalized, and licensing information is derived. Logs a warning if documentation URLs are missing for non-deprecated, non-SQL driver connectors that indicate cloud support.
    *
-   * @returns {array} - The translated and enriched data.
+   * @param {object} parsedData - Parsed CSV data containing connector rows.
+   * @param {array} pages - Array of page objects used to resolve documentation URLs.
+   * @param {object} logger - Logger instance for warning about missing documentation.
+   * @returns {array} Array of enriched connector objects with normalized fields and URLs.
    */
   function translateCsvData(parsedData, pages, logger) {
     return parsedData.data.map(row => {
@@ -139,12 +139,17 @@ module.exports.register = function ({ config }) {
         }
       }
 
-      // Log a warning if neither URL was found (only warn for missing cloud if it should support cloud)
-      // Ignore sql_driver connectors because they are not real connectors and only used as a utility for grouping sql driver types.
-      if (!connector.includes('sql_driver') && !redpandaConnectUrl && (!redpandaCloudUrl && is_cloud_supported === 'y')) {
+      // Log a warning if neither URL was found and the component is not deprecated
+      if (
+        deprecated !== 'y' &&
+        !connector.includes('sql_driver') &&
+        !redpandaConnectUrl &&
+        (!redpandaCloudUrl && is_cloud_supported === 'y')
+      ) {
         logger.warn(`Docs missing for: ${connector} of type: ${type}`);
       }
 
+
       // Return the translated and enriched row
       return {
         connector,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.5.0",
+  "version": "4.6.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -20,7 +20,8 @@
     "get-redpanda-version": "doc-tools get-redpanda-version",
     "get-console-version": "doc-tools get-console-version",
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
-    "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs"
+    "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
+    "test": "jest"
   },
   "contributors": [
     {
@@ -56,8 +57,7 @@
     "./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/data-template": "./macros/data-template.js"
+    "./macros/helm-ref": "./macros/helm-ref.js"
   },
   "files": [
     "extensions",
@@ -101,6 +101,7 @@
   "devDependencies": {
     "@antora/cli": "3.1.4",
     "@antora/site-generator": "3.1.4",
-    "@web/dev-server": "^0.2.5"
+    "@web/dev-server": "^0.2.5",
+    "jest": "^29.7.0"
   }
 }