Redirects and URL stability

Set up redirects to preserve links when you restructure your docs.

When you rename, move, or delete pages, existing links break. Redirects let you preserve those links and maintain SEO value when your docs structure changes.

Setting up redirects

Add a redirects array to your docs.json:

"redirects": [
  {
    "source": "/old-path/page",
    "destination": "/new-path/page"
  },
  {
    "source": "/getting-started/old-name",
    "destination": "/quickstart"
  }
]

Redirects are 301 (permanent) by default. Mintlify applies them at the CDN level, so they’re fast.

When to use redirects

Use redirects whenever you:

• Rename a page.
• Move a page to a different section.
• Delete a page and want to point visitors to a related page.
• Restructure your navigation hierarchy.

Wildcard redirects

Use wildcards to redirect entire sections at once:

{
  "source": "/old-section/:path*",
  "destination": "/new-section/:path*"
}

This redirects /old-section/page-a to /new-section/page-a, /old-section/page-b to /new-section/page-b, and so on.

Keeping URLs stable

The best way to avoid broken links is to keep URLs stable from the start:

• Choose page slugs that reflect the content’s purpose, not its position in the navigation.
• Use short, descriptive slugs that won’t need to change when content evolves.
• Avoid including version numbers in slugs unless you’re explicitly versioning your docs.

Before a major restructure, run a link check on your docs and on external sites that link to you. Prioritize redirects for high-traffic pages and frequently linked anchors.