Replace visual diffing with page link resolution in preview-docs workflow (#3492)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: kenny@buildwithfern.com <kenny@buildwithfern.com>

Author: devin-ai-integration[bot]

.github/workflows/preview-docs.yml

@@ -23,13 +23,8 @@ jobs:
           git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-${{ github.event.pull_request.number }}
           git checkout pr-${{ github.event.pull_request.number }}
 
-      - name: Install Fern and CML
-        run: |
-          npm install -g fern-api@latest
-          npm install -g @dvcorg/cml
-
-      - name: Install Chrome for Puppeteer
-        run: npx puppeteer browsers install chrome@141.0.7390.54
+      - name: Install Fern
+        run: npm install -g fern-api@latest
 
       - name: Generate preview URL
         id: generate-docs
@@ -42,105 +37,43 @@ jobs:
           echo "preview_url=$URL" >> $GITHUB_OUTPUT
           echo "Preview URL: $URL"
 
-      - name: Run fern docs diff for changed MDX files
-        id: docs-diff
+      - name: Get page links for changed MDX files
+        id: page-links
         env:
           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
         run: |
           PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}"
           CHANGED_FILES=$(git diff --name-only origin/main...HEAD -- '*.mdx' 2>/dev/null || echo "")
           
           if [ -z "$CHANGED_FILES" ] || [ -z "$PREVIEW_URL" ]; then
-            echo "has_diffs=false" >> $GITHUB_OUTPUT
-            exit 0
+            echo "page_links=" >> $GITHUB_OUTPUT; exit 0
           fi
           
-          # Convert newlines to space-separated list for the command
-          FILES_LIST=$(echo "$CHANGED_FILES" | tr '\n' ' ')
-          
-          # Create output directory
-          mkdir -p .fern/diff
-          
-          # Run fern docs diff and capture output
-          # Progress messages go to stderr, JSON goes to stdout
-          # We capture everything to a temp file, then extract just the JSON
-          npx fern-api@latest docs diff "$PREVIEW_URL" $FILES_LIST --output .fern/diff > .fern/diff/output.txt 2>&1 || true
+          BASE_URL=$(echo "$PREVIEW_URL" | grep -oP 'https?://[^/]+')
           
-          # Extract just the JSON part (starts with { and ends with })
-          # The JSON is the last thing output, so we find the line starting with { and take everything from there
-          sed -n '/^{/,$p' .fern/diff/output.txt > .fern/diff/diff.json
+          FILES_PARAM=$(echo "$CHANGED_FILES" | tr '\n' ',' | sed 's/,$//')
+          RESPONSE=$(curl -sf -H "FERN_TOKEN: $FERN_TOKEN" "${PREVIEW_URL}/api/fern-docs/get-slug-for-file?files=${FILES_PARAM}" 2>/dev/null) || {
+            echo "page_links=" >> $GITHUB_OUTPUT; exit 0
+          }
           
-          # Debug: show what we captured
-          echo "=== Raw output ==="
-          cat .fern/diff/output.txt
-          echo "=== Extracted JSON ==="
-          cat .fern/diff/diff.json
+          PAGE_LINKS=$(echo "$RESPONSE" | jq -r --arg url "$BASE_URL" \
+            '.mappings[] | select(.slug != null) | "- [\(.slug)](\($url)/\(.slug))"')
           
-          # Check if diff JSON file exists and has valid content
-          if [ -f ".fern/diff/diff.json" ] && grep -q '"diffs"' .fern/diff/diff.json 2>/dev/null; then
-            echo "has_diffs=true" >> $GITHUB_OUTPUT
+          if [ -n "$PAGE_LINKS" ]; then
+            { echo "page_links<<EOF"; echo "$PAGE_LINKS"; echo "EOF"; } >> $GITHUB_OUTPUT
           else
-            echo "has_diffs=false" >> $GITHUB_OUTPUT
-            echo "No diffs found or diff.json is invalid"
+            echo "page_links=" >> $GITHUB_OUTPUT
           fi
 
-      - name: Upload diff images as artifacts
-        if: steps.docs-diff.outputs.has_diffs == 'true'
-        uses: actions/upload-artifact@v4
-        with:
-          name: docs-diff-images
-          path: .fern/diff/*.png
-          retention-days: 7
-
-      - name: Upload images and create comment
-        if: steps.docs-diff.outputs.has_diffs == 'true'
-        env:
-          REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }}
+      - name: Create comment content
         run: |
-          # Parse diff.json and upload images using cml
-          PREVIEW_URL="${{ steps.generate-docs.outputs.preview_url }}"
-          BASE_URL=$(echo "$PREVIEW_URL" | grep -oP 'https?://[^/]+')
-          
-          echo ":herb: **Preview your docs:** <${PREVIEW_URL}>" > comment.md
-          echo "" >> comment.md
-          echo "### Visual changes detected:" >> comment.md
-          echo "" >> comment.md
+          echo ":herb: **Preview your docs:** <${{ steps.generate-docs.outputs.preview_url }}>" > comment.md
           
-          # Process each diff entry
-          jq -c '.diffs[]' .fern/diff/diff.json | while read -r diff; do
-            FILE=$(echo "$diff" | jq -r '.file')
-            SLUG=$(echo "$diff" | jq -r '.slug')
-            COMPARISON=$(echo "$diff" | jq -r '.comparison')
-            CHANGE_PERCENT=$(echo "$diff" | jq -r '.changePercent // "N/A"')
-            IS_NEW_PAGE=$(echo "$diff" | jq -r '.isNewPage')
-            
-            echo "#### \`${FILE}\`" >> comment.md
-            echo "" >> comment.md
-            echo "**Page:** [${SLUG}](${BASE_URL}/${SLUG}) | **Change:** ${CHANGE_PERCENT}%" >> comment.md
-            if [ "$IS_NEW_PAGE" = "true" ]; then
-              echo " | *New page*" >> comment.md
-            fi
+          if [ -n "${{ steps.page-links.outputs.page_links }}" ]; then
             echo "" >> comment.md
-            
-            # Upload image using cml and get URL
-            if [ -f "$COMPARISON" ]; then
-              IMAGE_URL=$(cml publish "$COMPARISON" 2>/dev/null || echo "")
-              if [ -n "$IMAGE_URL" ]; then
-                echo "![${FILE} comparison](${IMAGE_URL})" >> comment.md
-              else
-                echo "*Comparison image available in [workflow artifacts](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*" >> comment.md
-              fi
-            fi
-            echo "" >> comment.md
-          done
-          
-          cat comment.md
-
-      - name: Create comment without diffs
-        if: steps.docs-diff.outputs.has_diffs != 'true'
-        run: |
-          echo ":herb: **Preview your docs:** <${{ steps.generate-docs.outputs.preview_url }}>" > comment.md
+            echo "Here are the markdown pages you've updated:" >> comment.md
+            echo "${{ steps.page-links.outputs.page_links }}" >> comment.md
+          fi
 
       - name: Post PR comment
         uses: thollander/actions-comment-pull-request@v2.4.3