A redirect map is a plain list with one row for every address your current site answers on, and a decision written next to each one about what that address should point at after the move. It is built before the migration, not after, and it is finished when every row has a decision rather than when the list stops growing. Nearly all of the work is inventory and judgment. The technical part, actually putting the redirects in place, is the short step at the end, and it cannot begin until the map exists.
Two things need to be true before you start building it. The first is the backup and rollback plan this cluster treats as non-negotiable, because a redirect map is only useful if the site it describes still exists to be checked against. The second is specific to this job: agree a content freeze, with a stated start and a stated end, with everyone who publishes. A map is written against a moving target. If posts are being published, renamed or deleted while the map is being built, the map describes a site that no longer exists by the time anyone uses it, and nobody will notice until the addresses that were added during the freeze period turn out to be missing from it.
What the map is, what it is not, and where the search questions go
The map is an inventory with decisions attached. That is all. It is usually a spreadsheet, and the minimum useful shape is two columns: the address as it exists now, and the address it should resolve to afterward. Most people add a third for notes, because the interesting rows need explaining.
It is worth being clear about what this article covers and what it does not, because the subject sits next to a much larger one.
Covered here: building and verifying the map as a migration deliverable. Where the list of old addresses comes from, how to freeze it, how to match old to new, what to do with the rows that have no obvious destination, the categories that get missed, and how to test the result before and after cutover.
Not covered here, deliberately: how any of this affects search performance. Whether a redirect should be permanent or temporary as a search signal, what chains of redirects do to how pages are assessed, canonicals, and the question of what any individual URL deserves to become are all questions about how a page performs rather than about moving content, and they belong with an on-page search resource rather than this one. The dividing line worth holding in your head: are you moving and repairing content, or deciding how a page should perform in search? This article is entirely the first. When you reach a decision that turns on the second, that is the moment to go and get a search answer rather than guess at one here.
That boundary is genuinely useful rather than a formality, because the two jobs have different owners on most teams and the map is where they meet.
Building the inventory, and freezing it
The single most common way a redirect map fails is that it is built from one source and the site has addresses from several.
Crawl the site. Any tool that follows every link from your homepage and records what it finds will produce the bulk of the list. This catches everything reachable by clicking.
Add your sitemaps. These often contain addresses the crawl did not reach, because nothing links to them anymore. Orphaned content is still content, and it is still answering on an address today.
Add your analytics. Export every address that received a visit over the longest period you have. This is the source that catches the things the other two miss entirely: old landing pages, addresses shared in a newsletter years ago, anything that was linked from somewhere else and never from your own navigation.
Add anything you have pointed people at deliberately. Addresses used in email campaigns, printed material, social profiles, or documentation. These are frequently not on the site at all in any linkable sense and are exactly the ones whose breakage is most embarrassing.
Combine, remove duplicates, and then freeze it. Save the combined list as a dated file and treat it as fixed. From this point, changes to the site are changes to the map, and somebody has to make them deliberately. This is what the content freeze is protecting. Without the freeze, the map and the site drift apart quietly, and the drift is invisible because both look correct on their own.
One useful habit while combining: keep the visit count from analytics alongside each address. You are not using it to judge whether a page is worth keeping, which is a different question with a different owner. You are using it to decide what to check by hand first, because a map of any size cannot be verified row by row and the addresses people actually use are the ones worth your attention.
Matching old to new, one row at a time
For most rows this is mechanical. The post existed, it still exists, and it has a new address. Write it down.
The mechanical rows usually follow a pattern, and it is worth establishing the pattern early on a sample rather than assuming one. Migrations change the shape of addresses as well as the domain, and often not uniformly. Renamed posts whose address no longer matches their title, posts with unusual characters, and content that lived under a section the new platform organizes differently are the standard exceptions. If your sample turns up more than one pattern, you have more than one rule, and knowing that now is much cheaper than discovering it during cutover.
Match one to one wherever the content survived. One old address, one new address, no cleverness. A row that sends several old addresses to a single new one is sometimes correct, but it should be a decision you made rather than a shortcut you took because the mapping was tedious.
Record the rule you used, not just the result. If four hundred rows follow one transformation, write the transformation down at the top of the sheet. It makes the map reviewable by someone other than its author, and it makes the inevitable second pass possible.
The rows with no destination
This is the part that takes the time, and it is the part the map exists to force.
Some addresses have no equivalent on the new site, and there is no way to write the map without deciding what happens to each of them. The usual categories:
Content that was merged. Three thin posts became one substantial one. All three old addresses are real and all three need a decision.
Content that was split. One long post became four. The old address has four candidate destinations and only one can be chosen.
Content that is being retired. A migration is the most honest content audit most sites ever get, because every piece of content has to be looked at to be moved. Some of it will not be coming. That is a legitimate outcome and it still needs a row.
Addresses that were never content. Feeds, search result pages, filtered views, print versions, and anything else the old platform generated as a byproduct. These answered on real addresses and may have been linked from somewhere.
For each of these the map needs an entry, and the entry needs to say something. What it should say, specifically, depends on judgments about how those pages ought to perform, which is not this article’s to answer. What is this article’s to say is the process point: a row with no decision written in it is not a finished row, and a map that is complete except for the hard rows is not a complete map. The hard rows are the reason the document exists. If they are still empty on the day of cutover, they will be resolved by whatever the new platform does by default, which is a decision nobody made.
Handle these while the old site is still up and readable. Once it is gone, working out what a retired address used to contain means going through backups, and the judgment gets made with less information than it deserved.
The categories that get missed, because they are not posts
A content inventory lists content. These are all addresses your site answers on that no content inventory will ever show you:
Paginated series. Archive pages, category listings and long posts split across several pages each have their own address. Their numbering rarely survives a platform change intact.
Parameterized addresses. Anything carrying a query string: filters, sorts, tracking parameters, session identifiers. Decide as a category rather than row by row, but decide, because they are frequently linked from outside.
Media and attachment addresses. Some platforms give every uploaded file its own page as well as its own file address. Both are addresses. What happens to them is covered from the content side in what happens to your images when you move platforms, and the address side belongs in this map.
Term archives. Every category and tag has a listing page at its own address. When classification is restructured during a move, and it usually is, those addresses change or disappear along with it. Why categories and tags never survive a migration intact covers what happens to the terms; the map is where you record what happens to their addresses.
Author pages, date archives and feeds. Present on most platforms, absent or differently shaped on many others, and linked from more places than anyone expects.
Case and trailing slashes. Platforms differ on whether an address with a trailing slash and one without are the same address, and on whether capitalization matters. This produces a class of failure that is invisible in a spreadsheet and obvious in production. Establish what the destination does before cutover, not after.
Testing it before cutover, and again afterward
A map is a document, and documents are wrong. Two rounds of checking, and they look for different things.
Before cutover, against the new site wherever it is being built. Take the map and check that every destination address actually exists. This is the round that catches the typos, the rows written against a naming convention that changed during the build, and the destinations that were planned and never made. Check the whole map mechanically if you can, and check by hand the rows that carry the most traffic and every row you had to think about.
After cutover, against the live site. Take the same map and request every old address. Each should arrive at the destination the map names, in one step. The failures here are usually rows that were correct in the document and implemented incorrectly, plus whatever the freeze failed to catch.
Then check the site’s own links separately. A redirect map is about people and systems arriving from outside. Your own posts linking to your own old addresses is a different problem with a different fix, and it is covered in repairing internal links after a migration. A working redirect layer will make those internal links appear to work, which is precisely why they get left broken for years. The map is not a substitute for repairing them.
Keep the map. It is the record of what your site used to be, and it is the only place the decisions about the retired and merged content are written down. It stays useful long after the migration, and the next person to ask “what happened to that old page” will have no other source. For where this step sits in the overall sequence, the migration guide sets out the order, and the 12 things that break in every CMS migration covers what else is moving while you are doing this.
FAQ
Do I have to keep the same URLs forever?
No, but every address your site currently answers on needs a decision written down before it changes. Changing addresses is normal during a platform move. Changing them without a map is how content becomes unreachable with nobody noticing.
When should the map be built?
Before the migration, alongside a content freeze. Built afterward it is a reconstruction from backups rather than an inventory, and the rows that need judgment get made with less information.
What goes in the map for a page that no longer exists?
A decision, whatever it is. The categories that produce these rows are merged content, split content, retired content, and addresses that were never really content. What the right decision is for each depends on how you want those pages to perform, which is a search question rather than a migration one, but leaving the row empty is not an option: something will happen to that address whether or not anyone chose it.
Which addresses get forgotten most often?
The ones that are not posts. Paginated archives, parameterized addresses, media and attachment pages, category and tag listings, author and date archives, and feeds. None of them appears in a content inventory and all of them are real addresses.
Is the map still useful after the migration is done?
Yes, and it is worth keeping permanently. It is the only written record of what the site used to contain and what was decided about the content that did not come across.
Written July 2026. Platform address handling and import behavior change over time; verify the specifics of your own source and destination platforms before relying on any detail above.
