Customize

Redirects

Configure URL redirects to manage page moves, URL changes, and legacy paths in your documentation site.

Overview

Redirects allow you to automatically send visitors from one URL to another. This is essential when you reorganize your documentation structure, rename pages, or need to maintain backward compatibility with old URLs.

Redirects are processed at the middleware level before any page rendering occurs. The first matching redirect in your configuration takes precedence.

When to use redirects

Common use cases for redirects include:

Page moves: Redirect old URLs when you reorganize your documentation structure
URL changes: Maintain links when renaming pages or changing URL slugs
Legacy support: Keep old bookmarks and external links working
Content consolidation: Redirect multiple old pages to a single new page
Version migrations: Redirect users from deprecated API versions to current ones

Configuration

Redirects are configured in your documentation.json file under the redirects property:

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    }
  ]
}

Redirect properties

Property	Type	Required	Description
`source`	`string`	Yes	The incoming path pattern to match. Supports dynamic segments with `:paramName` syntax.
`destination`	`string`	Yes	The target path to redirect to. Can include dynamic parameters from the source.
`statusCode`	`301 \| 302 \| 307 \| 308`	No	HTTP status code for the redirect. Defaults to `308`.

Status codes

Choose the appropriate status code based on your redirect scenario:

Code	Name	Use Case
`301`	Moved Permanently	Permanent redirect. May change request method to GET. Best for SEO when content has permanently moved.
`302`	Found	Temporary redirect. May change request method to GET. Use for temporary moves.
`307`	Temporary Redirect	Temporary redirect that preserves the request method. Use for temporary moves with POST/PUT requests.
`308`	Permanent Redirect	Permanent redirect that preserves the request method. Default. Best for permanent moves.

Use 308 (the default) for most permanent redirects. It's the modern replacement for 301 and preserves the HTTP method, which is important for API documentation.

Basic redirects

Simple page redirect

Redirect a single page to a new location:

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    }
  ]
}

Multiple redirects

Define multiple redirects in the array:

{
  "redirects": [
    {
      "source": "/getting-started",
      "destination": "/docs/quickstart"
    },
    {
      "source": "/api-docs",
      "destination": "/api-reference"
    },
    {
      "source": "/faq",
      "destination": "/support/faqs"
    }
  ]
}

Redirect with custom status code

Specify a status code for temporary or specific redirect behaviors:

{
  "redirects": [
    {
      "source": "/maintenance",
      "destination": "/status",
      "statusCode": 307
    },
    {
      "source": "/legacy-api",
      "destination": "/v2/api",
      "statusCode": 301
    }
  ]
}

Dynamic redirects

Dynamic redirects use path parameters to match patterns and transfer values to the destination URL.

Parameter syntax

Use :paramName syntax to define dynamic segments:

{
  "redirects": [
    {
      "source": "/docs/:slug",
      "destination": "/documentation/:slug"
    }
  ]
}

This redirect matches:

/docs/quickstart → /documentation/quickstart
/docs/api-reference → /documentation/api-reference
/docs/getting-started → /documentation/getting-started

Multiple parameters

You can use multiple parameters in a single redirect:

{
  "redirects": [
    {
      "source": "/api/:version/:endpoint",
      "destination": "/reference/:version/:endpoint"
    }
  ]
}

This redirect matches:

/api/v1/users → /reference/v1/users
/api/v2/products → /reference/v2/products

Reorganizing parameters

Parameters can be reordered or selectively used in the destination:

{
  "redirects": [
    {
      "source": "/blog/:year/:month/:slug",
      "destination": "/articles/:slug"
    }
  ]
}

This redirect matches:

/blog/2024/01/my-post → /articles/my-post

Dynamic parameters only match single path segments. The pattern /docs/:slug will match /docs/quickstart but will not match /docs/api/users (which has two segments after /docs/).

Pattern matching behavior

Understanding how redirects match URLs helps you configure them correctly.

Trailing slashes

Trailing slashes are normalized during matching. Both /docs/ and /docs will match a source pattern of /docs:

{
  "redirects": [
    {
      "source": "/docs",
      "destination": "/documentation"
    }
  ]
}

Matches both:

/docs → /documentation
/docs/ → /documentation

Case sensitivity

Path matching is case-sensitive. /Docs will not match a source of /docs:

{
  "redirects": [
    {
      "source": "/docs",
      "destination": "/documentation"
    }
  ]
}

/docs → /documentation ✓
/Docs → No match ✗

Segment count matching

The number of path segments must match exactly. A pattern with two segments won't match a path with three segments:

{
  "redirects": [
    {
      "source": "/docs/:slug",
      "destination": "/documentation/:slug"
    }
  ]
}

/docs/quickstart → /documentation/quickstart ✓ (2 segments)
/docs/api/users → No match ✗ (3 segments)

Processing order

Redirects are processed in the order they appear in your configuration array. The first matching redirect wins.

Place more specific redirects before general ones to ensure they take precedence.

{
  "redirects": [
    {
      "source": "/docs/api/deprecated",
      "destination": "/docs/api/v2"
    },
    {
      "source": "/docs/:slug",
      "destination": "/documentation/:slug"
    }
  ]
}

In this example:

/docs/api/deprecated matches the first rule (specific)
/docs/quickstart matches the second rule (general)

Subpath deployments

If your documentation is deployed at a subpath (e.g., example.com/docs), redirects are automatically adjusted:

The subpath is prepended to the source for matching
The subpath is prepended to the destination if not already present

You don't need to include the subpath in your redirect configuration:

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    }
  ]
}

For a subpath deployment at /docs:

Request to /docs/old-page → Redirects to /docs/new-page

Examples

Documentation restructure

When reorganizing your documentation hierarchy:

{
  "redirects": [
    {
      "source": "/guides/getting-started",
      "destination": "/quickstart"
    },
    {
      "source": "/guides/installation",
      "destination": "/getting-started/installation"
    },
    {
      "source": "/guides/configuration",
      "destination": "/getting-started/configuration"
    },
    {
      "source": "/reference/api",
      "destination": "/api-reference/overview"
    }
  ]
}

API version migration

When deprecating an API version:

{
  "redirects": [
    {
      "source": "/api/v1/:endpoint",
      "destination": "/api/v2/:endpoint",
      "statusCode": 301
    },
    {
      "source": "/api/v1",
      "destination": "/api/v2",
      "statusCode": 301
    }
  ]
}

Content consolidation

When merging multiple pages into one:

{
  "redirects": [
    {
      "source": "/troubleshooting/errors",
      "destination": "/support/troubleshooting"
    },
    {
      "source": "/troubleshooting/faq",
      "destination": "/support/troubleshooting"
    },
    {
      "source": "/help/common-issues",
      "destination": "/support/troubleshooting"
    }
  ]
}

Temporary maintenance redirect

When temporarily redirecting during maintenance:

{
  "redirects": [
    {
      "source": "/api-playground",
      "destination": "/maintenance",
      "statusCode": 307
    }
  ]
}

Best practices

Troubleshooting

Was this page helpful?

Built with Documentation.AI

Last updated 1 week ago