Preserve URLs and redirects

A migration usually changes your page URLs — the new platform lays out paths differently, and section names shift as you restructure. Left unhandled, every inbound link, bookmark, and search result that points at an old URL breaks. Redirects are the difference between a migration your readers never notice and one that scatters 404s across your traffic.

Warning

Don’t skip redirects because “the content is all still there.” Search engines and every external link still point at the old paths. Without redirects, that accumulated link equity and those bookmarks land on 404 pages the day you cut over.

Build a URL map

Before you flip the switch, record where every old URL lands in the new structure. A simple two-column mapping — old path to new path — is enough:

Old path	New path
/kb/getting-started	/docs/start-here/quickstart
/reference/api-overview	/docs/reference/api

Capture this while you’re moving content, when the correspondence is freshest. Every page whose URL changes needs an entry; pages whose URL is unchanged don’t.

If your source platform can export a list of published URLs, start from that export so you don’t miss a page. Crawling your live site is another way to enumerate every URL that needs a destination.

Add the redirects

How you apply the map depends on the target platform, but the mechanism is always the same: a permanent (HTTP 301) redirect from each old path to its new one.

1. Find your platform’s redirect mechanism. Most static site generators and hosts support redirects through a config file or a hosting-level rules file — for example, a redirects map in your site config, or a redirects/rewrites file for your host. Check your target platform’s and host’s documentation for the supported format.

2. Add an entry for every changed URL. Translate each row of your URL map into a redirect rule from the old path to the new path, marked permanent (301) so search engines transfer ranking to the new URL.

3. Handle whole-section moves. When an entire section moves under a new prefix, a single wildcard or pattern redirect often covers all its pages instead of one rule per page — if your platform supports pattern-based rules.

Verify before and after cut-over

Confirm the redirects resolve before you point your domain at the new site, and again once it’s live:

• Spot-check high-traffic URLs from your analytics — your most-visited old paths should land on the right new pages.
• Crawl for broken links with a link checker so no internal link or redirect points at a dead path.
• Watch for 404s after cut-over in your host or analytics logs, and backfill any redirect you missed.

Redirects and Promptless

Redirect handling belongs to your documentation platform and host, not to Promptless — Promptless proposes content changes through pull requests and doesn’t manage your hosting-level redirects. That said, once your migrated docs are connected as a doc collection, Promptless keeps the content current from that point forward, so the migration is the one-time cost and staying current is automatic afterward.

Planning a migration and want help getting the redirect strategy right? Contact help@gopromptless.ai.