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 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:
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.
