Redirects

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
{  "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

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:

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

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

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

SEO Best Practices

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