> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Redirects

Configure URL redirects to handle moved, renamed, or deprecated documentation pages.

## Overview

When you rename pages, restructure your documentation, or deprecate content, incoming links to the old URLs will break. Redirects solve this by forwarding visitors (and search engines) from old paths to new ones, preserving SEO value and preventing dead links.

Configure redirects in the `redirects` array in your `docs.json` file.

## Basic Configuration

Add a `redirects` array at the top level of your `docs.json`:

```json docs.json
{
  "name": "My Docs",
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    },
    {
      "source": "/guides/setup",
      "destination": "/quickstart"
    }
  ]
}
```

When a visitor navigates to `/old-page`, they are automatically redirected to `/new-page`.

## Redirect Properties

| Property | Type | Default | Description |
|---|---|---|---|
| `source` | string | Required | The old URL path to redirect from |
| `destination` | string | Required | The new URL path or full URL to redirect to |
| `permanent` | boolean | `true` | `true` for 301 (permanent), `false` for 302 (temporary) |

## Permanent vs Temporary Redirects

### Permanent Redirects (301)

The default behavior. A 301 redirect tells browsers and search engines that the page has moved permanently. Search engines transfer the SEO value (link equity) from the old URL to the new one.

```json
{
  "source": "/api/v1/users",
  "destination": "/api/v2/users",
  "permanent": true
}
```

Use 301 redirects when:

- A page has been renamed or moved to a new location
- Your URL structure has changed permanently
- You are migrating from a previous documentation platform
- Content has been consolidated into another page

### Temporary Redirects (302)

A 302 redirect indicates the move is temporary. Search engines keep the old URL indexed and do not transfer SEO value.

```json
{
  "source": "/changelog",
  "destination": "/blog/whats-new",
  "permanent": false
}
```

Use 302 redirects when:

- Content is temporarily hosted elsewhere
- You are running an A/B test on different page structures
- A page is under maintenance and will return to its original URL

Using 302 when you mean 301 dilutes your SEO. If a page has permanently moved, always use `"permanent": true` (or omit the field, since `true` is the default).

## Glob Patterns

Use glob patterns to redirect groups of pages with a single rule. This is useful when moving entire sections of your documentation.

### Wildcard Matching

The `*` wildcard matches any path segment:

```json
{
  "redirects": [
    {
      "source": "/docs/*",
      "destination": "/*"
    }
  ]
}
```

This redirects `/docs/quickstart` to `/quickstart`, `/docs/guides/setup` to `/guides/setup`, and so on.

### Section Moves

Redirect an entire section to a new location:

```json
{
  "redirects": [
    {
      "source": "/reference/*",
      "destination": "/api/*"
    }
  ]
}
```

`/reference/users` becomes `/api/users`, `/reference/projects` becomes `/api/projects`, etc.

### Specific Overrides with Globs

When you have both glob patterns and specific redirects, specific rules take precedence:

```json
{
  "redirects": [
    {
      "source": "/v1/*",
      "destination": "/v2/*"
    },
    {
      "source": "/v1/deprecated-endpoint",
      "destination": "/v2/new-endpoint"
    }
  ]
}
```

`/v1/deprecated-endpoint` redirects to `/v2/new-endpoint` (specific rule), while all other `/v1/*` paths redirect to their `/v2/*` equivalents (glob rule).

## Common Use Cases

### Page Renames

The most common redirect scenario. When you rename a file, add a redirect so existing links continue to work.

```json
{
  "redirects": [
    {
      "source": "/getting-started",
      "destination": "/quickstart"
    },
    {
      "source": "/faq",
      "destination": "/troubleshooting"
    }
  ]
}
```

### Documentation Restructuring

When reorganizing your docs into a new directory structure:

```json
{
  "redirects": [
    {
      "source": "/authentication",
      "destination": "/guides/authentication"
    },
    {
      "source": "/deployment",
      "destination": "/guides/deployment"
    },
    {
      "source": "/configuration",
      "destination": "/reference/configuration"
    }
  ]
}
```

### Version Migration

When releasing a new API version and redirecting old version URLs:

```json
{
  "redirects": [
    {
      "source": "/api/v1/*",
      "destination": "/api/v2/*"
    },
    {
      "source": "/api/v1/legacy-auth",
      "destination": "/api/v2/authentication"
    }
  ]
}
```

### Deprecated Content

Redirect removed pages to the most relevant replacement:

```json
{
  "redirects": [
    {
      "source": "/integrations/zapier",
      "destination": "/integrations"
    },
    {
      "source": "/sdk/ruby",
      "destination": "/sdk"
    }
  ]
}
```

### External Redirects

Redirect to pages outside your documentation site:

```json
{
  "redirects": [
    {
      "source": "/community",
      "destination": "https://discord.gg/holydocs"
    },
    {
      "source": "/github",
      "destination": "https://github.com/holydocs"
    }
  ]
}
```

### Platform Migration

When migrating from another documentation platform, redirect old URL patterns to their HolyDocs equivalents:

**From Mintlify**

```json
    {
      "redirects": [
        {
          "source": "/introduction",
          "destination": "/quickstart"
        },
        {
          "source": "/api-reference/*",
          "destination": "/api/*"
        }
      ]
    }
    ```
  **From GitBook**

```json
    {
      "redirects": [
        {
          "source": "/~/changes",
          "destination": "/changelog"
        },
        {
          "source": "/v/*/",
          "destination": "/"
        }
      ]
    }
    ```
  **From Docusaurus**

```json
    {
      "redirects": [
        {
          "source": "/docs/*",
          "destination": "/*"
        },
        {
          "source": "/blog/*",
          "destination": "https://yourdomain.com/blog/*"
        }
      ]
    }
    ```

## SEO Best Practices

**Redirect, never delete**

When removing or renaming a page, always add a redirect. Deleting a page without a redirect creates a 404, which wastes any SEO authority the page had accumulated and frustrates visitors following old links.
  **Prefer permanent redirects**

Use 301 (permanent) redirects for any change you do not plan to revert. This signals to search engines that the new URL is canonical, transferring ranking signals.
  **Avoid redirect chains**

Never redirect A to B and then B to C. Each hop adds latency and dilutes SEO value. If you have moved a page multiple times, update all redirects to point directly to the final destination.
  **Redirect to the most specific page**

When deprecating content, redirect to the most relevant replacement page, not the homepage. A redirect from `/api/v1/users` to `/api/v2/users` is far more useful than redirecting to `/`.
  **Audit redirects periodically**

As your documentation grows, review your redirects list to remove entries where the source URL no longer receives traffic. Large redirect lists add processing overhead to every request.

Redirects are evaluated at the edge before any page rendering occurs. They add negligible latency — typically under 5ms — to the redirected request.