diff --git a/.github/workflows/validate-mdx.yml b/.github/workflows/validate-mdx.yml
index 673ecea0dc..a2c39957dc 100644
--- a/.github/workflows/validate-mdx.yml
+++ b/.github/workflows/validate-mdx.yml
@@ -9,6 +9,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v6
         with:
           node-version: '20'
diff --git a/scripts/mdx-validation/validate-mdx-mintlify.sh b/scripts/mdx-validation/validate-mdx-mintlify.sh
index ebaef91ba9..3da0ca629f 100755
--- a/scripts/mdx-validation/validate-mdx-mintlify.sh
+++ b/scripts/mdx-validation/validate-mdx-mintlify.sh
@@ -18,13 +18,47 @@ cleanup() {
 # Trap to ensure cleanup
 trap cleanup EXIT INT TERM
 
+# Check if there are any MDX files in the changeset
+if [ -n "$GITHUB_BASE_REF" ]; then
+  # In a PR context, check changed files
+  echo "Checking for changed MDX files in PR..."
+  
+  # Get the list of changed files
+  CHANGED_MDX=$(git diff --name-only "origin/$GITHUB_BASE_REF"...HEAD -- '*.mdx' 2>/dev/null | grep -E '\.mdx$' || true)
+  
+  if [ -z "$CHANGED_MDX" ]; then
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "NO MDX FILES CHANGED"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "No MDX files found in this PR. Skipping validation."
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    exit 0
+  fi
+  
+  echo "Found changed MDX files:"
+  echo "$CHANGED_MDX" | sed 's/^/  /'
+  echo ""
+fi
+
 echo "Starting Mintlify validation..."
 echo ""
 echo "Running: mint dev --no-open (will run for ${PARSE_TIME}s to parse all files)"
 echo ""
 
 # Run mint dev with tee to force output writing, timeout after PARSE_TIME seconds
-timeout --preserve-status ${PARSE_TIME}s mint dev --no-open 2>&1 | tee "$LOGFILE" > /dev/null || true
+# Use timeout if available (Linux), otherwise use gtimeout (macOS with coreutils), or perl as fallback
+if command -v timeout > /dev/null 2>&1; then
+  timeout --preserve-status ${PARSE_TIME}s mint dev --no-open 2>&1 | tee "$LOGFILE" > /dev/null || true
+elif command -v gtimeout > /dev/null 2>&1; then
+  gtimeout --preserve-status ${PARSE_TIME}s mint dev --no-open 2>&1 | tee "$LOGFILE" > /dev/null || true
+else
+  # Fallback: run mint dev in background and kill after PARSE_TIME
+  mint dev --no-open 2>&1 | tee "$LOGFILE" > /dev/null &
+  PID=$!
+  sleep ${PARSE_TIME}
+  kill "$PID" 2>/dev/null || true
+  wait "$PID" 2>/dev/null || true
+fi
 
 echo ""
 echo "✓ Mintlify finished parsing"
@@ -47,11 +81,28 @@ if grep -q "parsing error" "$LOGFILE"; then
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
   exit 1
-else
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo "✅ MINTLIFY VALIDATION PASSED"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo "No parsing errors detected by Mintlify"
-  exit 0
 fi
 
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ MINTLIFY PARSING VALIDATION PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "No parsing errors detected by Mintlify"
+echo ""
+
+# Run broken links check
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "CHECKING FOR BROKEN LINKS"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Running: mint broken-links"
+echo ""
+
+# Run mint broken-links - it will exit with non-zero if broken links are found
+mint broken-links
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ ALL VALIDATION CHECKS PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "- No parsing errors"
+echo "- No broken links"
+exit 0