From aee1920292d26ddbb8cbc633952e24213077f5a0 Mon Sep 17 00:00:00 2001
From: Julian Pawlowski <jpawlowski@users.noreply.github.com>
Date: Thu, 9 Apr 2026 18:41:41 +0000
Subject: [PATCH] chore(pre-commit): add docusaurus build guard for changed
 docs sites

Add a local pre-commit hook that builds Docusaurus when files under
docs/user or docs/developer are staged.

Introduced scripts/docs/build-changed-sites to detect which docs site
was touched and run only the required npm build(s).

Impact: Prevents broken MDX/Docusaurus changes from being committed by
failing fast in pre-commit before CI.
---
 .pre-commit-config.yaml          |  9 +++++++
 scripts/docs/build-changed-sites | 43 ++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 scripts/docs/build-changed-sites

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index fa5aa51..caf2df9 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -21,3 +21,12 @@ repos:
         language: system
         types: [python]
         require_serial: true
+
+      # Build changed Docusaurus site(s) to catch MDX/build errors early
+      - id: docusaurus-build-changed-sites
+        name: docusaurus build (changed sites)
+        entry: bash scripts/docs/build-changed-sites
+        language: system
+        files: ^docs/(user|developer)/
+        pass_filenames: true
+        require_serial: true
diff --git a/scripts/docs/build-changed-sites b/scripts/docs/build-changed-sites
new file mode 100644
index 0000000..4c473e2
--- /dev/null
+++ b/scripts/docs/build-changed-sites
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Build only Docusaurus site(s) impacted by current staged file set.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+build_user=false
+build_developer=false
+
+for file in "$@"; do
+    case "$file" in
+        docs/user/*)
+            build_user=true
+            ;;
+        docs/developer/*)
+            build_developer=true
+            ;;
+    esac
+done
+
+if [[ "$build_user" == false && "$build_developer" == false ]]; then
+    exit 0
+fi
+
+if [[ "$build_user" == true ]]; then
+    echo "Building user docs (docs/user)..."
+    (
+        cd docs/user
+        npm run build
+    )
+fi
+
+if [[ "$build_developer" == true ]]; then
+    echo "Building developer docs (docs/developer)..."
+    (
+        cd docs/developer
+        npm run build
+    )
+fi
+
+echo "Docusaurus build check passed for changed docs site(s)."