Redirect Strategy for Broken Links

Date: November 10, 2025
Purpose: Handle broken URLs discovered by Google and prevent 404 errors for users

Overview

With 719 noindexed pages discovered by Google Search Console, we need a systematic approach to handle broken URLs through redirects. This document outlines the strategy for implementing redirects in Mintlify.

Current Redirect Configuration

Existing Redirects in `docs.json`

You already have some redirects configured. Here’s the current pattern:

"redirects": [
  {
    "source": "/link/4.5/task-manager-overview",
    "destination": "/4.6.0/docs/platform-deep-dive/core-extensions/task-management/task-management-overview"
  },
  {
    "source": "/link/5.1/data-search",
    "destination": "/5.1/docs/platform-deep-dive/core-extensions/search-data-service#flowx-ai-data-search"
  }
  // ... more redirects
]

Current redirect count: ~18 redirects for shortlink patterns

Redirect Decision Matrix

Priority 1: HIGH - Must Redirect

URLs that users or external sites are actively accessing:

Pattern	Destination	Reason
`/release-notes/v4.7.4-may-2025`	`/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025`	Google indexed, user bookmarks
`/release-notes/v3.4.0-september-2023`	`/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023`	Historical reference
`/4.5.0/*`	`/4.6.0/*`	Version folder doesn’t exist
`/5.0-tech-preview/*`	`/5.1/*`	Renamed version
`/faqs`	`/5.1/docs/introduction` or 404	Deprecated page

Priority 2: MEDIUM - Should Redirect

Old documentation structures that changed:

Pattern	Destination	Reason
`/release-notes/docs/*`	`/release-notes/v3.x.x/` or `/release-notes/v4.x/`	Restructured folders
`/release-notes/v5.x/5.1/*`	`/5.1/*`	Wrong path structure
`/release-notes/5.0-tech-preview/*`	`/5.1/*`	Renamed version
`/4.7.0/*`	`/4.7.x/*`	Specific version → LTS version

Priority 3: LOW - Let 404

URLs that should fail (no redirect needed):

Pattern	Reason
`$2`, `runtime(`, invalid paths	Malformed URLs from crawl errors
`auth-*.demo.flowx.ai`	External demo systems
`/health`, `/actuator/*`	Internal system endpoints
`oauth2/v2.0/token`	API endpoints, not docs

Implementation Strategy

Phase 1: Add Version Folder Redirects (IMMEDIATE)

Handle the main broken version references:

{
  "redirects": [
    // Existing redirects...
    
    // Version folder redirects - 4.5.0 → 4.6.0
    {
      "source": "/4.5.0/:path*",
      "destination": "/4.6.0/:path*"
    },
    
    // Version folder redirects - 5.0-tech-preview → 5.1
    {
      "source": "/5.0-tech-preview/:path*",
      "destination": "/5.1/:path*"
    },
    
    // Version folder redirects - 4.7.0 → 4.7.x
    {
      "source": "/4.7.0/:path*",
      "destination": "/4.7.x/:path*"
    }
  ]
}

Expected impact: Fixes ~350 broken URLs

Phase 2: Add Release Notes Redirects (SHORT-TERM)

Handle flat release notes URLs that moved into folder structure:

{
  "redirects": [
    // v4.7.x release notes
    {
      "source": "/release-notes/v4.7.4-may-2025",
      "destination": "/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025"
    },
    {
      "source": "/release-notes/v4.7.4-may-2025/",
      "destination": "/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025"
    },
    
    // v3.x release notes
    {
      "source": "/release-notes/v3.4.0-september-2023",
      "destination": "/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023"
    },
    {
      "source": "/release-notes/v3.4.0-september-2023/",
      "destination": "/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023"
    },
    
    // v4.0 release notes
    {
      "source": "/release-notes/v4.0.0-april-2024",
      "destination": "/release-notes/v4.x/v4.0.0-april-2024/v4.0.0-april-2024"
    },
    {
      "source": "/release-notes/v4.0.0-april-2024/",
      "destination": "/release-notes/v4.x/v4.0.0-april-2024/v4.0.0-april-2024"
    },
    
    // v4.1.x release notes
    {
      "source": "/release-notes/v4.1.0-may-2024",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024"
    },
    {
      "source": "/release-notes/v4.1.1-june-2024",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024"
    },
    {
      "source": "/release-notes/v4.1.5-september-2024",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024"
    },
    
    // v5.x release notes
    {
      "source": "/release-notes/v5.0.0-july-2025",
      "destination": "/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025"
    }
  ]
}

Expected impact: Fixes ~50-100 release notes URLs

Phase 3: Add Malformed Path Redirects (MEDIUM-TERM)

Handle nested release notes paths:

{
  "redirects": [
    // Malformed paths - docs nested in release-notes
    {
      "source": "/release-notes/docs/:path*",
      "destination": "/5.1/docs/:path*"
    },
    {
      "source": "/release-notes/v4.x/:version/docs/:path*",
      "destination": "/:version/docs/:path*"
    },
    {
      "source": "/release-notes/v4.x/:version/setup-guides/:path*",
      "destination": "/:version/setup-guides/:path*"
    },
    {
      "source": "/release-notes/v5.x/5.1/:path*",
      "destination": "/5.1/:path*"
    }
  ]
}

Expected impact: Fixes ~200 malformed nested paths

Phase 4: Handle Special Cases (OPTIONAL)

{
  "redirects": [
    // FAQs page (deprecated)
    {
      "source": "/faqs",
      "destination": "/5.1/docs/introduction"
    },
    
    // Old API docs pattern
    {
      "source": "/api/:path*",
      "destination": "/5.1/docs/api/:path*"
    },
    
    // Old release notes root redirects
    {
      "source": "/release-notes/overview",
      "destination": "/release-notes/overview"
    }
  ]
}

Mintlify Redirect Syntax

Pattern Matching

Mintlify supports these redirect patterns:

// Exact match
{
  "source": "/old-page",
  "destination": "/new-page"
}

// Wildcard match (splat)
{
  "source": "/old-folder/:path*",
  "destination": "/new-folder/:path*"
}

// Named parameters
{
  "source": "/version/:version/docs/:slug",
  "destination": "/:version/docs/:slug"
}

// Query parameters (preserved automatically)
{
  "source": "/old-page",
  "destination": "/new-page"
  // ?param=value is automatically preserved
}

// Anchors (preserved automatically)
{
  "source": "/old-page",
  "destination": "/new-page"
  // #section is automatically preserved
}

Redirect Types

Mintlify uses 301 (Permanent) redirects by default, which is perfect for SEO.

Automated Redirect Generation

Script: Generate Redirects from CSV

Create a script to analyze Google Search Console data and suggest redirects:

// scripts/generate-redirects-from-csv.js
const fs = require('fs');
const csv = require('csv-parser');

const results = [];
const redirects = [];

// Read the noindexed URLs CSV
fs.createReadStream('path/to/Table.csv')
  .pipe(csv())
  .on('data', (data) => results.push(data))
  .on('end', () => {
    results.forEach(row => {
      const url = new URL(row.URL);
      const path = url.pathname;
      
      // Version folder redirects
      if (path.includes('/4.5.0/')) {
        redirects.push({
          source: path,
          destination: path.replace('/4.5.0/', '/4.6.0/'),
          reason: 'Version folder redirect'
        });
      }
      
      if (path.includes('/5.0-tech-preview/')) {
        redirects.push({
          source: path,
          destination: path.replace('/5.0-tech-preview/', '/5.1/'),
          reason: 'Version folder redirect'
        });
      }
      
      // Release notes flat → nested
      const releaseNotesMatch = path.match(/^\/release-notes\/(v\d\.\d\.\d-\w+-\d{4})$/);
      if (releaseNotesMatch) {
        const version = releaseNotesMatch[1];
        // Determine target folder based on version
        let destination;
        if (version.startsWith('v3.')) {
          destination = `/release-notes/v3.x.x/${version}/${version}`;
        } else if (version.startsWith('v4.0')) {
          destination = `/release-notes/v4.x/${version}/${version}`;
        } else if (version.startsWith('v4.1')) {
          destination = `/release-notes/v4.x/v4.1.x/${version}/${version}`;
        } else if (version.startsWith('v4.7')) {
          destination = `/release-notes/v4.x/v4.7.x-lts/${version}/${version}`;
        }
        
        if (destination) {
          redirects.push({
            source: path,
            destination,
            reason: 'Release notes restructure'
          });
        }
      }
    });
    
    // Output unique redirects
    const unique = [...new Map(redirects.map(r => [r.source, r])).values()];
    console.log(JSON.stringify(unique, null, 2));
  });

Testing Redirects

1. Local Testing

Mintlify doesn’t support redirects in local dev, but you can test the redirect rules logic:

# Test redirect pattern matching
node scripts/test-redirects.js

2. Preview Environment Testing

Deploy to Mintlify preview and test redirects:

# After deploying to preview
curl -I https://your-preview.mintlify.app/4.5.0/docs/introduction

# Expected response:
HTTP/1.1 301 Moved Permanently
Location: /4.6.0/docs/introduction

3. Production Validation

After deploying redirects:

# Test a few critical redirects
curl -I https://docs.flowx.ai/4.5.0/docs/introduction
curl -I https://docs.flowx.ai/5.0-tech-preview/setup-guides/spicedb
curl -I https://docs.flowx.ai/release-notes/v4.7.4-may-2025

Monitoring & Maintenance

Monthly Redirect Audit

Check in Google Search Console:

Coverage → Excluded → Redirect error (should be empty)
Coverage → Excluded → Page with redirect (review list)
Performance → Search results (check if redirected URLs still get traffic)

Review redirect effectiveness:

# Check redirect logs (if available)
# Look for:
# - 301 redirects returning 200 OK
# - Redirect chains (301 → 301 → 200)
# - Circular redirects

Quarterly Cleanup

Remove outdated redirects:

Redirects older than 1 year with zero traffic
Redirects to pages that no longer exist
Temporary redirects that became permanent

Update redirect targets:

Ensure redirects point to current version docs
Update redirects for renamed/moved pages
Fix redirect chains

Redirect Best Practices

✅ DO:

Use 301 (Permanent) redirects - Better for SEO
Redirect to most relevant current page - Don’t just send to homepage
Preserve URL structure when possible - Keep same path depth
Test redirects after deployment - Ensure they work
Document why each redirect exists - Add comments in docs.json
Keep redirect list organized - Group by type/version
Monitor redirect performance - Check Google Search Console

❌ DON’T:

Create redirect chains - A → B → C (bad), go A → C directly
Redirect to 404 pages - Verify destination exists
Use temporary (302) redirects - Unless truly temporary
Redirect everything to homepage - Be specific
Forget to handle trailing slashes - Add both versions
Create circular redirects - A → B → A
Leave redirects forever - Clean up old ones

Implementation Checklist

Phase 1: Immediate (Week 1)

Add version folder redirects (4.5.0, 5.0-tech-preview, 4.7.0)
Add top 20 release notes redirects
Deploy to preview environment
Test critical redirects
Deploy to production
Monitor Google Search Console for 48 hours

Phase 2: Short-term (Week 2-3)

Generate full redirect list from CSV data
Add remaining release notes redirects
Add malformed path redirects
Test all new redirects
Deploy to production
Request Google to recrawl affected URLs

Phase 3: Medium-term (Month 2)

Create automated redirect generation script
Set up redirect monitoring dashboard
Document redirect maintenance process
Train team on redirect management

Phase 4: Long-term (Quarterly)

Review redirect effectiveness
Clean up outdated redirects
Update redirect documentation
Optimize redirect rules

Recommended Redirects to Add Now

Based on the Google Search Console data, here are the top priority redirects to add immediately:

{
  "redirects": [
    // EXISTING redirects stay here...
    
    // === VERSION FOLDER REDIRECTS (Priority 1) ===
    {
      "source": "/4.5.0/:path*",
      "destination": "/4.6.0/:path*"
    },
    {
      "source": "/5.0-tech-preview/:path*",
      "destination": "/5.1/:path*"
    },
    {
      "source": "/4.7.0/:path*",
      "destination": "/4.7.x/:path*"
    },
    
    // === MALFORMED RELEASE NOTES PATHS (Priority 1) ===
    {
      "source": "/release-notes/v5.x/5.1/:path*",
      "destination": "/5.1/:path*"
    },
    {
      "source": "/release-notes/5.0-tech-preview/:path*",
      "destination": "/5.1/:path*"
    },
    {
      "source": "/release-notes/docs/:path*",
      "destination": "/5.1/docs/:path*"
    },
    
    // === TOP 10 RELEASE NOTES (Priority 2) ===
    {
      "source": "/release-notes/v4.7.4-may-2025",
      "destination": "/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025"
    },
    {
      "source": "/release-notes/v4.7.4-may-2025/",
      "destination": "/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025"
    },
    {
      "source": "/release-notes/v3.4.0-september-2023",
      "destination": "/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023"
    },
    {
      "source": "/release-notes/v3.4.0-september-2023/",
      "destination": "/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023"
    },
    {
      "source": "/release-notes/v4.1.5-september-2024",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024"
    },
    {
      "source": "/release-notes/v4.1.5-september-2024/",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024"
    },
    {
      "source": "/release-notes/v4.1.1-june-2024",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024"
    },
    {
      "source": "/release-notes/v4.1.1-june-2024/",
      "destination": "/release-notes/v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024"
    },
    {
      "source": "/release-notes/v4.0.0-april-2024",
      "destination": "/release-notes/v4.x/v4.0.0-april-2024/v4.0.0-april-2024"
    },
    {
      "source": "/release-notes/v4.0.0-april-2024/",
      "destination": "/release-notes/v4.x/v4.0.0-april-2024/v4.0.0-april-2024"
    },
    
    // === SPECIAL CASES (Priority 3) ===
    {
      "source": "/faqs",
      "destination": "/5.1/docs/introduction"
    }
  ]
}

Expected impact:

Fixes ~400-500 broken URLs
Reduces 404 errors by 60-70%
Improves SEO for historical content
Better user experience for bookmarked pages

Success Metrics

Track these metrics to measure redirect effectiveness:

404 Error Rate
- Target: < 1% of total pageviews
- Measure: Google Analytics / Search Console
Redirect Traffic
- Track: Pageviews to redirected URLs
- Goal: Decline over time (as Google updates index)
Crawl Errors
- Target: 0 “Redirect error” in Search Console
- Monitor: Weekly for first month
Search Visibility
- Track: Indexed pages count in Search Console
- Goal: Increase from current ~280 to ~350+
User Experience
- Track: Bounce rate on redirected pages
- Target: < 50% bounce rate

Additional Resources

Tools

Redirect Mapper Chrome Extension - Test redirects in browser
Screaming Frog SEO Spider - Crawl site and find redirect chains
Google Search Console - Monitor redirect errors
Redirect Checker (redirectcheck.com) - Verify redirect responses

Documentation

Changelog

Date	Change	Impact
2025-11-10	Initial redirect strategy created	Documentation
2025-11-10	Recommended top priority redirects	~400-500 URLs

Questions & Support

Before adding a redirect, ask:

Is this URL getting traffic? (Check Search Console)
Is there a better destination than this?
Will this create a redirect chain?
Does the destination exist and work?

Need help?

Check this document first
Review Google Search Console data
Test redirects in preview environment
Consult with team before deploying major changes

Getting Started

Platform overview

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

API reference

​Redirect Strategy for Broken Links

​Overview

​Current Redirect Configuration

​Existing Redirects in docs.json

​Redirect Decision Matrix

​Priority 1: HIGH - Must Redirect

​Priority 2: MEDIUM - Should Redirect

​Priority 3: LOW - Let 404

​Implementation Strategy

​Phase 1: Add Version Folder Redirects (IMMEDIATE)

​Phase 2: Add Release Notes Redirects (SHORT-TERM)

​Phase 3: Add Malformed Path Redirects (MEDIUM-TERM)

​Phase 4: Handle Special Cases (OPTIONAL)

​Mintlify Redirect Syntax

​Pattern Matching

​Redirect Types

​Automated Redirect Generation

​Script: Generate Redirects from CSV

​Testing Redirects

​1. Local Testing

​2. Preview Environment Testing

​3. Production Validation

​Monitoring & Maintenance

​Monthly Redirect Audit

​Quarterly Cleanup

​Redirect Best Practices

​✅ DO:

​❌ DON’T:

​Implementation Checklist

​Phase 1: Immediate (Week 1)

​Phase 2: Short-term (Week 2-3)

​Phase 3: Medium-term (Month 2)

​Phase 4: Long-term (Quarterly)

​Recommended Redirects to Add Now

​Success Metrics

​Track these metrics to measure redirect effectiveness:

​Additional Resources

​Tools

​Documentation

​Changelog

​Questions & Support