Redirects

Redirects forward users from old URLs to new ones. Use them when reorganizing docs, renaming pages, or maintaining links from previous documentation versions.

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 all paths under a prefix:

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

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

HTTP Status Codes

By default, redirects return a 308 (permanent redirect). Specify 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

When restructuring your navigation:

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

API Version Migration

When deprecating an API version:

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

External Redirects

Redirect to external URLs:

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

Preserving SEO

When pages have existing search rankings:

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

Redirect Order

Redirects are evaluated in order. More specific rules should come 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

After adding 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?