How to Create a URL Mapping for a Site Migration
The mapping is the migration. Everything else is either preparation for it or consequence of it. Almost every serious failure we see traces back to a map that was incomplete, wrong, else produced after the new site was built rather than before it.
This Is The Document The Migration Runs On
The map is a record of where every old address goes. It is the thing the redirects are built from, the thing the testing is done against and the thing anybody diagnosing a problem afterwards will need.
What it actually is. Two columns and a decision.
Every address that exists today, plus the address it will resolve to afterwards. That is the whole structure. The difficulty is entirely in completeness and in the quality of each decision.
Why its quality decides the outcome. Everything downstream inherits it.
Redirects built from an incomplete map are incomplete. Testing performed against a wrong map confirms the wrong thing. A recovery attempt with no map has nothing to check against.
Who should be able to read it. Both sides.
The person building the site and the person responsible for search. It is the one document both need, which is the argument in block eight for keeping it as a single thing.
What it is not. A technical artefact.
It records decisions rather than implementation. How the redirects are then created is a separate question, covered in how to implement 301 redirects.
Every Address, Not Every Page
A site has considerably more addresses than pages. A map built from the page list is therefore incomplete before anybody has made a single mapping decision. It is incomplete in the places that matter most.
What else resolves. Five categories.
Addresses carrying parameters, such as filters and sorting. Pagination, where a listing runs across several numbered addresses. Tag and category listings generated automatically. Search result addresses. And old addresses still reachable because a previous migration left redirects behind.
Why the last one matters most. It compounds.
A site that has moved before carries the addresses from that move. Those still receive traffic and still carry links. A map built from today's pages misses an entire previous generation of the site.
How the gap forms. The page list is what people can see.
Anybody asked to list a site's pages produces the navigation and the content they remember. Nothing in that process surfaces a parameter address from four years ago that a trade publication linked to once.
Where the complete list comes from. The audit.
Several sources combined, because none is complete alone, per site audit before migration.
One To One Wherever Possible
Each old address should point at the closest equivalent on the new site. Not a related page, not a parent section, not something in the same general area. The equivalent.
Why it preserves the most. The destination matches the expectation.
Somebody arriving from a link about a specific subject reaches a page about that subject. Anything assessing the move sees a page that corresponds to what the old one was about. Both of those hold together only when the match is genuine.
What counts as equivalent. Purpose rather than title.
The page that now does the job the old one did. A renamed page is still equivalent. A page covering a third of the old subject is not. Treating it as one is where approximate mapping starts.
What it costs. Time, unavoidably.
One to one takes longer than any shortcut, because somebody has to decide each case rather than applying a rule. That cost is the reason shortcuts exist and it is the reason they fail.
The real limit. Not everything has one.
Some old addresses genuinely have no equivalent, which is block five rather than a licence for approximation.
Do Not Send Everything To The Home Page
Pointing every unmatched old address at the home page is the single most common mapping shortcut. It is also the one that wastes exactly the value the migration was supposed to preserve.
What the vendor's own documentation says. Checked August 2026.
The published site move guidance states that many old addresses should not be redirected to one irrelevant destination such as the home page of the new site, that this can confuse users and that it might be treated as a soft error. That wording is deliberately hedged in the source and we have not hardened it here.
Why it happens anyway. It looks responsible.
Every address resolves. Nothing returns an error. A quick check finds no broken links. The site appears to have been migrated carefully, which is precisely why nobody investigates further.
What it costs. The reason for redirecting at all.
A redirect exists to carry what the old address had earned to a page that continues the same purpose. A destination with no relationship to the original has nothing to continue.
The legitimate version. Genuine consolidation.
The same documentation is explicit that where content previously held on several pages has actually been combined into one, redirecting those old addresses to the combined page is appropriate. The difference is whether the destination really contains what the originals did.
What To Do When There Is No Equivalent
Some old addresses have nowhere obvious to go. A product discontinued, a service withdrawn, an article about something that no longer exists. There are three defensible answers and one indefensible one.
The nearest genuinely relevant page. The first choice.
Something a person arriving from that link would find useful. A discontinued product pointing at its replacement, else at the category containing similar items.
A parent category. The second.
Where no individual equivalent exists, the section the old page belonged to is a reasonable destination, because somebody arriving there is at least in the right part of the site.
Letting it stop working. Sometimes correct.
Where content genuinely no longer exists and nothing is close, allowing the address to return not found is the correct answer. It tells the truth, which beats a redirect to something unrelated.
The condition on that. A decision, not an omission.
Recorded in the map as a deliberate choice. An address that stops working because somebody chose it and an address that stops working because somebody missed it look identical afterwards, which is why the record matters. Anything carrying external links is never a candidate.
Automated Matching Has Limits
Pattern matching handles the bulk of a large site quickly and reliably. The exceptions are where the value usually sits, which is an uncomfortable relationship worth understanding.
What automation does well. Predictable relationships.
Where old and new addresses differ by a consistent rule, thousands of them can be mapped at once with high confidence. On a large site this is most of the work and there is no reason to do it by hand.
Where it stops. Anything irregular.
Addresses that never followed the pattern, pages that were renamed for reasons nobody recorded, sections that were reorganised at some point and the leftovers from previous migrations.
Why those are the valuable ones. Age.
Irregular addresses are usually old ones. Old addresses have had the longest to accumulate external links. So the addresses automation cannot handle are disproportionately the ones carrying the most.
What follows. A split approach.
Automate the regular bulk. Map the priority list from the audit by hand, individually, with somebody deciding each one. That is a small amount of work applied where it matters most.
Map Before The New Site Is Finished
When the map is produced determines what it can achieve. Built early, it shapes the new site. Built late, it can only describe it.
What late mapping forces. Matching to whatever exists.
If the new site is finished, every old address has to be matched against the pages that happen to be there. Where something valuable has no destination, the answer is a compromise, because adding a page at that stage is a change request.
What early mapping allows. Shaping the destination.
If the map is built while the new structure is being decided, an important old page with no obvious equivalent can be given one. The new site is built to preserve value rather than assessed for whether it happened to.
When it can start. As soon as the crawl exists.
The old side of the map is available immediately. Destinations can be filled in as the new structure firms up, which spreads the longest task across the project instead of compressing it into the final fortnight.
Why projects leave it late. It feels like it depends on the build.
Half of it does. The half that does not is the half that takes the time.
Keep It As One Document
The map is the shared artefact between whoever builds and whoever is responsible for search. Split across several files or several people, it stops being any of those things.
Why fragmentation happens. Sections get delegated.
The blog is handled by one person, the shop by another, the old campaign addresses by whoever remembers them. Each produces a competent list. Nobody holds the whole picture, so gaps between the sections belong to nobody.
What one document gives you. A completeness check.
The total number of source addresses can be compared against the audit inventory. If those two numbers differ, something is missing. That comparison is impossible across fragmented lists.
What it becomes afterwards. The test plan.
The same document is what launch testing runs against, then what anybody diagnosing a later problem works from. That is block nine.
Why it should survive the project. The next one will need it.
A site that migrates once will migrate again. The map from this move is the record of a whole generation of addresses. Losing it means the next migration starts blind.
Test The Map Before Launch
A map is a plan until it has been checked against what was actually built. Until that check happens, nobody knows whether the redirects match the intention or merely exist.
What testing means here. Comparing two lists.
For each source address, confirming that it resolves to the destination the map specifies. Not that it resolves to something. That it resolves to the right thing.
Why a sample is not enough. Failures cluster.
Problems concentrate in particular address types rather than distributing evenly. A sample drawn from ordinary pages will pass while every parameter address fails, because the pattern that handled one did not cover the other.
What to cover instead. Every type, plus the priority list.
At minimum, examples of each address category and every address on the audit's priority list individually.
When to do it again. Immediately after launch.
Environments differ, so a redirect behaving correctly before launch can behave differently afterwards. Testing twice is the cheapest insurance in the project. What to do when it fails is in redirect errors and recovery after migration. The full series is on the website migration guide.
The mapping
is the
migration.
Every address mapped rather than every page, the closest genuine equivalent chosen rather than the nearest convenient one, nothing swept to the home page, retirements recorded as decisions so nobody later mistakes them for omissions, with the whole map tested against what was actually built before anybody goes live.
What a migration engagement covers:
A migration is a one-off project rather than a monthly service, so it is scoped and quoted against the size of the site and how much is changing at once.
Every guide.
One practice.
What a migration is, the types, when to do it, planning, the checklist, auditing, mapping, redirects, internal links, tags, downtime, crawling, structured data, performance, notifying, monitoring, recovery and the mistakes.
