Redirects

Redirects send readers from old URLs to new ones. Use them when you reorganize docs, rename pages, or keep links from previous documentation versions working.

Configuration

Add redirects to your docs.json:

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    },
    {
      "source": "/guides/setup",
      "destination": "/getting-started"
    }
  ]
}

Redirect Types

Exact Match

Redirects a specific URL:

{
  "source": "/api/v1/users",
  "destination": "/api/v2/users"
}

/api/v1/users → /api/v2/users

Wildcard Match

Use * to match path segments:

{
  "source": "/blog/*",
  "destination": "/articles/*"
}

/blog/hello-world → /articles/hello-world

Prefix Match

Redirect every path under a prefix:

{
  "source": "/v1/*",
  "destination": "/v2/*"
}

/v1/api/users → /v2/api/users

HTTP Status Codes

Redirects return 308 (permanent redirect) by default. Set a different status:

{
  "source": "/old-page",
  "destination": "/new-page",
  "statusCode": 307
}

Use 308 for most documentation redirects. Use 307 for temporary moves during migrations.

Common Patterns

Reorganizing Documentation

{
  "redirects": [
    { "source": "/setup", "destination": "/getting-started" },
    { "source": "/setup/install", "destination": "/getting-started/installation" },
    { "source": "/setup/config", "destination": "/getting-started/configuration" }
  ]
}

API Version Migration

{
  "redirects": [
    { "source": "/api/v1/*", "destination": "/api/v2/*" }
  ]
}

External Redirects

{
  "source": "/community",
  "destination": "https://discord.gg/your-server"
}

Preserving SEO

Keep search rankings for moved pages with a permanent redirect:

{
  "redirects": [
    {
      "source": "/tutorials/getting-started-with-api",
      "destination": "/quickstart",
      "statusCode": 301
    }
  ]
}

Redirect Order

Redirects are evaluated in order. Put specific rules before wildcards:

{
  "redirects": [
    { "source": "/api/v1/special-endpoint", "destination": "/api/special" },
    { "source": "/api/v1/*", "destination": "/api/v2/*" }
  ]
}

The first matching rule wins.

Limitations

• Redirects only apply to documentation paths
• Query parameters are preserved automatically
• Hash fragments are preserved automatically
• Maximum 1000 redirects per project

Testing Redirects

1. Deploy your changes
2. Visit the old URL directly
3. Verify you land on the new destination
4. Check the HTTP status code in browser dev tools

# Check redirect with curl
curl -I https://docs.example.com/old-page

What's Next?