The Scrivener's Ledger: On the Exact Transcription of a Domain Migration

There is a quiet, clerical terror in moving a website to a new domain. It’s not the server configuration or the DNS propagation that keeps me up at night. It’s the fear of the stray reference—the single, overlooked page, buried in some forgotten corner of the code or content, that still points a visitor, or a search engine, to the old address. This fear isn’t irrational; it’s the memory of a broken promise to the user. The solution isn’t just a global redirect. It’s a technique of exact transcription.

Most migrations rely on a catch-all rule in the .htaccess or server config—a blanket statement that says, “Anything from old.com goes to new.com.” This is the broad brush. It gets the big picture right but smudges the details. It takes old.com/essay/on-birds and sends it to new.com/essay/on-birds. Functional, yes. But what of old.com/essay/on-birds/?page=2? Or old.com/archive/2023/?sort=title? The blanket rule often drops those precious query strings, sending the user to a generic landing page, stripping away their specific intent. The user sought a particular fragment of your work, and you handed them a table of contents.

The technique, then, is the ledger. Before a single file is moved, you must become a scrivener of your own site. Your task is to build a complete, line-by-line inventory of every unique URL path your old domain answers to. This means crawling it not as a visitor, but as an archivist. Use a tool that respects and records every nuance: query strings, session IDs, uppercase and lowercase paths, even the parameters you think are irrelevant. Export this list—this ledger—as a simple text file, a spreadsheet, a database. It is your master copy.

With ledger in hand, you craft your redirect map not from assumption, but from evidence. This is the transcription. For each entry in the ledger, you write a corresponding, explicit destination on the new domain. The messy URL with three query parameters? It gets a dedicated line in your redirect configuration, pointing to its precise, equivalent location on the new site. This is meticulous, often tedious work. It requires you to understand the structure of both the old and new worlds intimately.

The payoff is not in elegance, but in fidelity. When the switch is thrown, every recorded path finds its new home with exacting precision. The user who bookmarked a filtered product view, the researcher who linked to a specific comment thread, the bot that indexed a paginated series—they all arrive not at a doorstep, but at the very room they left. The redirect ceases to be a polite suggestion and becomes a seamless continuation. The terror of the stray reference diminishes, because you have accounted for the known universe of your old domain. You haven’t just moved your site; you have faithfully translated its entire history, one precise line at a time.

Notes & further reading

A few pages I came back to while writing this: