feat: add broken links check script with api-reference filtering

.github/workflows/broken-links.yml

@@ -5,10 +5,10 @@ on:
     paths:
       - 'mintlify/**/*.mdx'
       - '.github/workflows/broken-links.yml'
+      - 'mintlify/check-links.sh'
 
 permissions:
   contents: read
-  pull-requests: write
 
 jobs:
   check-broken-links:
@@ -18,81 +18,16 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-
       - name: Install Mintlify CLI
         run: npm install -g mintlify
 
       - name: Run broken links check
-        id: broken-links
-        working-directory: mintlify
         run: |
-          echo "Running mint broken-links in mintlify directory..."
-
-          # Run broken links check and capture both stdout and stderr
-          set +e  # Don't exit on error
-          mint broken-links &> broken-links-output.txt
-          mint_exit_code=$?
-          set -e  # Re-enable exit on error
-
-          echo "mint_exit_code=$mint_exit_code" >> $GITHUB_OUTPUT
-
-          # Show original output for debugging
-          echo "Original mint output:"
-          cat broken-links-output.txt
+          echo "## 🔍 Checking for broken links (excluding /api-reference)..."
+          echo ""
 
-          # Always report success and pass through the raw output
-          echo "has_broken_links=false" >> $GITHUB_OUTPUT
-          echo "RAW_OUTPUT<<EOF" >> $GITHUB_OUTPUT
-          cat broken-links-output.txt >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+          # Run the check script
+          ./mintlify/check-links.sh
 
-      - name: Comment on PR
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const rawOutput = `${{ steps.broken-links.outputs.RAW_OUTPUT }}`;
-
-            const body = `## 📝 Broken Links Check Report
-
-            > **Note**: Entries under \`/api-reference/\` are likely false positives and can be ignored.
-
-            The following is the output from the broken links check:
-
-            \`\`\`
-            ${rawOutput}
-            \`\`\`
-            `;
-
-            // Find existing comment
-            const comments = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-            });
-
-            const existingComment = comments.data.find(comment => 
-              comment.user.login === 'github-actions[bot]' && 
-              comment.body.includes('Broken Links Check')
-            );
-
-            if (existingComment) {
-              // Update existing comment
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existingComment.id,
-                body: body
-              });
-            } else {
-              // Create new comment
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: context.issue.number,
-                body: body
-              });
-            }
+          echo ""
+          echo "> **Note**: Links to \`/api-reference/\` are automatically excluded from this check."

mintlify/CLAUDE.md

@@ -33,6 +33,13 @@ mint install
 - Install Mintlify CLI globally: `npm i -g mint`
 - Run commands from the root directory where `docs.json` is located
 
+### Testing
+```bash
+# Check for broken links (excluding /api-reference)
+./mintlify/check-links.sh
+```
+Run this test before committing any documentation changes to ensure all internal links are valid.
+
 ## Content Management
 
 - **MDX Files**: All documentation pages use MDX format combining Markdown with React components

mintlify/check-links.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+
+# Change to the mintlify directory
+cd "$(dirname "$0")"
+
+# Run mint broken-links and capture output
+echo "Checking for broken links in mintlify directory..."
+output=$(mint broken-links 2>&1)
+
+# Check if mint command failed completely
+if [ $? -ne 0 ] && [ -z "$output" ]; then
+    echo "Error: Failed to run 'mint broken-links' command"
+    exit 1
+fi
+
+# Check if no broken links were found at all
+if echo "$output" | grep -q "No broken links found"; then
+    echo "✅ No broken links found"
+    exit 0
+fi
+
+# Process the output to filter out api-reference links
+# First, let's identify files that ONLY have api-reference links
+has_non_api_links=false
+current_file=""
+file_has_non_api_links=false
+filtered_lines=""
+
+while IFS= read -r line; do
+    # Check if this is a file name line (ends with .mdx or .md)
+    if echo "$line" | grep -qE '\.(mdx?|md)$'; then
+        # If we had a previous file with non-api links, add it to output
+        if [ -n "$current_file" ] && [ "$file_has_non_api_links" = true ]; then
+            filtered_lines="${filtered_lines}${current_file}\n"
+        fi
+        current_file="$line"
+        file_has_non_api_links=false
+    # Check if this is a link line (contains ⎿ or →)
+    elif echo "$line" | grep -qE '⎿|→'; then
+        # Check if this link is NOT an api-reference link
+        if ! echo "$line" | grep -q "/api-reference"; then
+            file_has_non_api_links=true
+            has_non_api_links=true
+            filtered_lines="${filtered_lines}${line}\n"
+        fi
+    # Keep the summary line only if we have non-api links
+    elif echo "$line" | grep -q "found.*broken links"; then
+        continue  # Skip for now, we'll add our own summary
+    fi
+done <<< "$output"
+
+# Add the last file if it had non-api links
+if [ -n "$current_file" ] && [ "$file_has_non_api_links" = true ]; then
+    filtered_lines="${filtered_lines}${current_file}\n"
+fi
+
+# Output results
+if [ "$has_non_api_links" = true ]; then
+    echo "❌ Broken links found (excluding /api-reference):"
+    echo ""
+    printf "$filtered_lines"
+
+    # Count the actual broken links
+    link_count=$(printf "$filtered_lines" | grep -c "⎿\|→" || echo "0")
+    if [ $link_count -gt 0 ]; then
+        echo ""
+        echo "Total broken links (excluding /api-reference): $link_count"
+    fi
+    exit 1
+else
+    echo "✅ No broken links found (excluding /api-reference)"
+    exit 0
+fi