fix: resolve 'Invalid path to URI' warnings in link checker (#1546)

## Description

This PR fixes the "Invalid path to URI" warnings that were appearing in
the link checker workflow, as seen in [run
#17112628120](https://github.com/wandb/docs/actions/runs/17112628120/job/48537193784#step:5:91).

## Problem

The link checker was encountering relative links like
`/guides/hosting/hosting-options/self-managed/` in the markdown files
but couldn't resolve them without a base URL. This caused many warnings
in the workflow output.

## Solution

1. **Added `--base-url` parameter** to lychee so it can properly resolve
relative paths
2. **Dynamic base URL detection**:
   - For main branch: Uses production URL `https://docs.wandb.ai`
- For PR branches: Uses Cloudflare branch preview URL (e.g.,
`https://branch-name.docodile.pages.dev`)
3. **Proper branch name conversion** to match Cloudflare's format:
   - 28 character limit
   - Lowercase
   - Special characters replaced with hyphens
   - Leading/trailing hyphens removed
4. **Retry logic** for checking preview URL availability (new PRs may
take time to deploy)
5. **Clear reporting** of which base URL was used in the workflow
summary

## Benefits

- ✅ Eliminates "Invalid path to URI" warnings
- ✅ Checks links against the correct environment:
  - PR branches check against their preview deployment
  - Main branch checks against production
- ✅ Better visibility with base URL shown in workflow summary
- ✅ More accurate link checking for PRs (checks against PR's changes,
not production)

## Testing

The workflow now:
1. Detects if it's running on main or a PR branch
2. Constructs the appropriate Cloudflare preview URL for PRs
3. Tests if the preview is accessible (with retries)
4. Falls back to production URL if preview isn't ready
5. Uses the determined base URL for all link checking

This ensures relative links are properly resolved and checked against
the appropriate environment.

Author: mdlinville

.github/workflows/linkcheck.yml

@@ -23,12 +23,69 @@ jobs:
       - name: Ensure lychee output dir
         run: mkdir -p lychee
 
+      - name: Determine base URL
+        id: base-url
+        run: |
+          # Default to production URL
+          BASE_URL="https://docs.wandb.ai"
+          
+          # If we're on a PR branch, try to use Cloudflare preview URL
+          if [[ "${{ github.event_name }}" == "pull_request" ]] || [[ "${{ github.ref }}" != "refs/heads/main" ]]; then
+            # Extract branch name
+            BRANCH_NAME="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}"
+            
+            # Convert branch name to Cloudflare format:
+            # 1. Take first 28 chars of branch name (Cloudflare limit)
+            # 2. Convert to lowercase
+            # 3. Replace non-alphanumeric chars with hyphens
+            # 4. Remove leading/trailing hyphens
+            # 5. Collapse multiple hyphens
+            PREVIEW_BRANCH=$(echo "$BRANCH_NAME" | \
+              cut -c1-28 | \
+              tr '[:upper:]' '[:lower:]' | \
+              sed 's/[^a-z0-9]/-/g' | \
+              sed 's/^-*//' | \
+              sed 's/-*$//' | \
+              sed 's/--*/-/g')
+            
+            # Cloudflare branch preview URL format
+            PREVIEW_URL="https://${PREVIEW_BRANCH}.docodile.pages.dev"
+            
+            echo "Branch name: $BRANCH_NAME"
+            echo "Preview branch slug: $PREVIEW_BRANCH"
+            echo "Testing preview URL: $PREVIEW_URL"
+            
+            # Test if preview URL is accessible (with retries for new PRs)
+            for i in {1..3}; do
+              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$PREVIEW_URL" || echo "000")
+              if [[ "$HTTP_CODE" =~ ^(200|301|302|304)$ ]]; then
+                BASE_URL="$PREVIEW_URL"
+                echo "✓ Using Cloudflare branch preview URL: $BASE_URL"
+                break
+              else
+                echo "Attempt $i: Preview returned $HTTP_CODE"
+                if [[ $i -lt 3 ]]; then
+                  echo "Waiting 5 seconds before retry..."
+                  sleep 5
+                fi
+              fi
+            done
+            
+            if [[ "$BASE_URL" == "https://docs.wandb.ai" ]]; then
+              echo "⚠️ Cloudflare preview not accessible after retries, using production URL"
+            fi
+          else
+            echo "Running on main branch, using production URL"
+          fi
+          
+          echo "base_url=$BASE_URL" >> $GITHUB_OUTPUT
+
       - name: Link Checker
         id: lychee
         uses: lycheeverse/lychee-action@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          args: "--accept 200,429,403 --user-agent 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)' --scheme https --scheme http --max-concurrency 5 --max-retries 1 --retry-wait-time 2 --verbose --no-progress --require-https 'content/**/*.md' 'content/**/*.html' 'https://docs.wandb.ai/guides/' 'https://docs.wandb.ai/ref/' 'https://docs.wandb.ai/tutorials/' 'https://docs.wandb.ai/support/'"
+          args: "--accept 200,429,403 --user-agent 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)' --scheme https --scheme http --max-concurrency 5 --max-retries 1 --retry-wait-time 2 --verbose --no-progress --require-https --base-url '${{ steps.base-url.outputs.base_url }}' 'content/**/*.md' 'content/**/*.html' 'https://docs.wandb.ai/guides/' 'https://docs.wandb.ai/ref/' 'https://docs.wandb.ai/tutorials/' 'https://docs.wandb.ai/support/'"
           output: ./lychee/out.json
           format: json
           fail: false
@@ -132,6 +189,9 @@ jobs:
           echo "## Link Check Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           
+          echo "🔗 **Base URL:** ${{ steps.base-url.outputs.base_url }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
           if [[ "${{ steps.fix.outputs.has_changes }}" == "true" ]]; then
             echo "✅ Created PR #${{ steps.cpr.outputs.pull-request-number }} with auto-fixed links" >> $GITHUB_STEP_SUMMARY
           elif [[ "${{ steps.fix.outputs.has_report }}" == "true" ]]; then