# Redirects and Broken Links in a Docs Reorg: Cloud Config vs Static Hosting

**Quick answer:** When you reorganize documentation, old URLs break unless you add redirects and audit links. A hosted docs platform usually gives you a redirect configuration file and a built-in link checker, while a static site handles redirects through hosting rules and a build-time check. Either way, treat redirects as part of the migration, not an afterthought, and verify that every old path resolves so existing bookmarks and search results do not land on a 404.

## Why a reorg creates broken links

Renaming a section, moving a page into a folder, or flattening a structure changes the URL even when the content is unchanged. External links, bookmarks, search-indexed results, and cross-references inside the docs all point at the old path. A 404 here is costly because it interrupts a developer who arrived with a specific question, and it erodes the ranking the old page had built.

| Concern | Hosted docs platform | Static hosting |
| --- | --- | --- |
| Redirect definition | Platform config or front matter | Hosting rules or redirects file |
| Link checking | Often built into the build | A separate build-time tool |
| Preview | Deploy preview per branch | Static preview build |
| 404 behavior | Themed not-found page | Custom 404 plus hosting fallback |

## Declaring redirects

Most platforms accept a mapping from the old path to the new one, often with a status code. A permanent redirect uses 301, while a temporary move uses 302. Keep the mapping in version control so the history of moves is reviewable.

On static hosting, the same intent is expressed in the host's redirect rules, for example a configuration file that maps paths to destinations. The mechanism differs, but the discipline is identical: enumerate every old path and point it at a real new page.

## Auditing internal and external links

A link checker should run as part of the build and fail it on broken internal references, so a move that forgets a cross-reference is caught before deploy. External links are trickier because third-party sites change or go offline, so check them on a schedule and distinguish a broken internal link from a temporarily unreachable external one.

`# Build-time check: fail on broken internal links, report external ones docs-cli check-links --src ./docs --fail-on-internal --report external`

## Preserving search equity during a move

A 301 passes most of the authority a page accumulated to the new URL, which is why a redirect is preferable to deleting and recreating a page. Avoid redirect chains, where one old path redirects to another path that also redirects, because each hop adds latency and weakens the signal. Point each old URL directly at its final destination. After launch, watch the 404 logs and the indexed pages to catch the paths the migration missed rather than assuming the redirect list was complete.

## Using previews to verify the reorg

Build a preview for the reorganizing branch and walk the old URLs against the new configuration before merging. Confirm that a sample of bookmarks, deep links, and search results resolve, and that the themed 404 page offers a way back to search or the index. A hosted platform makes this easy with automatic previews; on a static site, the CI build can serve the output for the same check. The goal is to discover broken paths in a preview, not in production analytics.

## How an AI agent can help and where it fails

An agent can generate the redirect mapping by comparing the old and new file trees, and it can rewrite internal links in bulk. That is a good fit because the change is mechanical. It cannot know which external links matter or which old URLs receive the most traffic, so supply the analytics and prioritize the high-traffic paths. Verify the generated mapping for accidental redirects to the wrong page and add a link-checking step to CI. Treat the agent's output as a first draft that the build and the preview must validate.

## Handling renamed anchors and deep links

Not every broken link is a full page move. Renaming a heading usually changes the generated anchor, so deep links that point at a specific section, including those in support articles and saved comments, break even though the page itself still loads. Include anchor mappings in the redirect plan where the platform supports them, and adopt a stable heading-ID convention so future edits do not regenerate identifiers. After launch, review the 404 log for requests that include a fragment or a deep path, because those indicate a broken anchor rather than a missing page and are easy to miss if you only check top-level URLs.

## Frequently asked questions

### Should I use 301 or 302 for reorganized docs?

Use 301 for a permanent move so the new URL inherits ranking and bookmarks update, and reserve 302 for a temporary change. A docs reorg is usually permanent.

### What is wrong with redirect chains?

Each hop adds latency and can weaken the authority passed to the final page. Map every old URL directly to its final destination rather than chaining through intermediate moves.

### How do I catch broken links before deploy?

Run a link checker in the build and fail on broken internal links, then use a deploy preview to walk old URLs against the redirect configuration. Check external links on a schedule.

### Do I need to keep old pages available?

You can remove the old content as long as its path redirects to the new page. Serving both duplicates content and confuses search; the redirect is the cleaner migration.

This is part of the [Powerduck vs Mintlify: API Documentation in the AI Era](https://www.powerduck.com/blog/powerduck-vs-mintlify/) — start there for the full comparison of hosted and static documentation workflows.