<!--
Sitemap:
- [What is Vocs](/introduction/what-is-vocs): Learn why Vocs exists and when to use it
- [Getting Started](/introduction/getting-started): Install Vocs and create your first documentation site
- [Project Structure](/introduction/project-structure): Overview of the structure of a Vocs project
- [Writing Docs with AI](/introduction/writing-docs-with-ai): Use an AI agent to create and maintain Vocs documentation
- [Markdown Extensions](/writing/markdown-extensions): Features and syntax of Markdown in Vocs
- [Code & Syntax Highlighting](/writing/syntax-highlighting): Rich markup and annotations for code
- [Twoslash](/writing/twoslash): Add type-aware annotations to code examples
- [Code Snippets](/writing/code-snippets): Include and reuse code in Markdown
- [Markdown Snippets](/writing/markdown-snippets): Include other Markdown files in MDX
- [React in Markdown](/writing/react): Compose MDX pages with React components
- [Mermaid Diagrams](/writing/mermaid): Render diagrams from text using Mermaid
- [Assets](/writing/assets): Manage images, fonts, icons, and other docs assets
- [Frontmatter](/writing/frontmatter): Configure page metadata, layouts, search, and UI visibility
- [Navigation](/features/navigation): Keep docs navigation synced with routes
- [Search](/features/search): Built-in client-side search powered by MiniSearch
- [Layouts](/features/layouts): Choose and customize page shells for your docs
- [Slots](/features/slots): Inject custom components into the docs shell
- [Theming](/features/theming): Customize colors, typography, spacing, logos, and code themes
- [Tailwind CSS](/features/tailwind): Use Tailwind utilities in Vocs pages and components
- [Dynamic OG Images](/features/dynamic-og-images): Generate social preview images from page metadata
- [Page Feedback](/features/feedback): Collect page-level feedback from readers
- [Redirects](/features/redirects): Preserve old URLs and route legacy paths to new locations
- [API Routes](/features/api-routes): Add server-rendered endpoints to your docs site
- [Agent Support](/features/agent-support): Serve documentation in machine-readable form for AI agents
- [Ask AI](/features/ask-ai): Built-in AI assistant menu on every page
- [MCP Server](/features/mcp-server): Expose your docs and source code to AI assistants
- [Changelog Generation](/features/changelog-generation): Fetch release notes and render a changelog page
- [Site Configuration](/reference/site-config): Reference for options accepted by defineConfig
- [Frontmatter Reference](/reference/frontmatter): All frontmatter fields accepted by a Vocs MDX page
- [Components](/reference/components): Reference for the public React components exported from Vocs
- [Hooks](/reference/hooks): Reference for the React hooks exported from Vocs
- [Changelog](/changelog): Release history for Vocs
-->

# Redirects \[Preserve old URLs and route legacy paths to new locations]

Use the [`redirects`](/reference/site-config#redirects) option in `vocs.config.ts` to map incoming request paths to new destinations. Redirects keep external links, search results, and bookmarks working when you move or rename pages.

## Basic Usage

```ts twoslash
import { defineConfig } from 'vocs/config'

export default defineConfig({
  redirects: [
    { source: '/docs', destination: '/introduction/getting-started' },
    { source: '/old-page', destination: '/new-page' },
  ],
})
```

A request to `/docs` returns an HTTP 307 redirect to `/introduction/getting-started`.

## Status Codes

Set `status` to control the HTTP status. Vocs uses `307` (temporary, preserves method) by default. Use `301` or `308` for permanent moves so search engines update their indices.

```ts
redirects: [
  // Permanent move (cached aggressively, preserves method)
  { source: '/v1/intro', destination: '/introduction/what-is-vocs', status: 308 },

  // Permanent move (legacy clients may downgrade POST → GET)
  { source: '/legacy', destination: '/', status: 301 },

  // Temporary redirect (default)
  { source: '/beta', destination: '/features/search' },
]
```

Supported statuses: `301`, `302`, `307`, `308`.

## Wildcards

Use `:path*` to redirect an entire subtree, preserving the trailing path:

```ts
redirects: [
  { source: '/old/:path*', destination: '/new/:path*' },
]
```

A request to `/old/guides/installation` redirects to `/new/guides/installation`.

## Named Parameters

Use `:name` for a single path segment:

```ts
redirects: [
  { source: '/blog/:slug', destination: '/articles/:slug' },
]
```

`/blog/hello-world` → `/articles/hello-world`.

## Common Patterns

### Moving a Documentation Section

When restructuring docs, add a one-to-one redirect for every renamed page:

```ts
redirects: [
  { source: '/guide/getting-started', destination: '/introduction/getting-started' },
  { source: '/guide/structure',       destination: '/introduction/project-structure' },
  { source: '/guide/twoslash',        destination: '/writing/twoslash' },
]
```

### Collapsing a Versioned Path

```ts
redirects: [
  { source: '/v1/:path*', destination: '/:path*' },
]
```

### Canonicalizing a Slug

```ts
redirects: [
  { source: '/sign-in', destination: '/login', status: 308 },
]
```

## Tips

* Add redirects in the **same commit** that moves a page so external links never break.
* Use `301`/`308` for permanent moves so they get cached and indexed correctly.
* Avoid chaining redirects (A → B → C). Always point old paths directly at their final destination.
* Pair with [`checkDeadlinks`](/reference/site-config#checkdeadlinks) so internal links stay accurate.

## See Also

* [Site Configuration · `redirects`](/reference/site-config#redirects)
* [Navigation](/features/navigation)