How to do a website content migration

The steps outlined in this post have been rattling around in my head for a few years now, but I've just been too busy to get them down.

Well, here we are now, and whilst nothing is ever definitive, this post sets out the main points that should be covered in a content migration.

What do I know?

I've hand-crafted this process a ton of times for a bunch of different sites and CMS technologies over the last decade or more.

Be warned - this is a long one, and has a fair bit of tech-speak.

Ready?

Planning and executing a content data migration: what's actually involved

Moving content from one system to another sounds simple in principle - export the old, import the new.

In practice, a well-run migration is closer to a small engineering project: it has a discovery phase, a data model, a set of scripts, and a testing cycle.

The rest of this post walks through what's involved, from the initial decision of whether to automate at all through to the final import.

Should the migration be automated?

Not every migration needs a script.

Before building anything, it's worth doing a simple cost comparison: will writing and testing a programmatic import take less time than moving the content by hand?

For a handful of pages - let's say ten or so - manual migration is often faster and involves less risk than building a custom toolset.

For hundreds or thousands of pages, spread across multiple content types with relational data attached, automation quickly becomes the only realistic option.

This calculation should happen early, since it shapes the entire project timeline and budget.

The content audit

Once automation is the preferred route, the next step is understanding exactly what's being moved, and where it's going.

Mapping the content data models

This starts with mapping the content types on both sides: what page type or content type is the data currently stored as, and what type is it moving into?

These rarely match one-to-one, so the audit needs to identify where the source and target systems overlap, and where the target's data model, front-end rendering, and admin interface can actually support what's being brought across.

Any field, tag, or structure that isn't supported on the destination side needs a decision early on: convert it, simplify it, or drop it.

Content data export

This is also the point to look at the existing system itself and its export options.

Content should be exportable as CSV or other tabular data, and these exports should be deterministic and repeatable, so that the same export run multiple times always produces the same result.

That repeatability matters because migrations are rarely a single event; the export will likely be run many times during development and testing before the final import.

Any content that needs manual editing or cleanup outside of the automated process - content that can't simply be exported and transformed - should be identified now, with a content freeze or refresh plan put in place so that the data format stays stable and predictable in the run-up to the final migration.

Relational data and media files

Relational data needs its own treatment.

Taxonomy terms, categories, media files, and other linked records typically need to be exported separately from the main content, each with unique IDs or URLs that let them be re-linked to their parent content during import.

We don't need to take everything with us

The audit should also decide what to leave behind.

Not every field needs to make the journey - some may be redundant, deprecated, or simply not needed in the new system.

Handling HTML and embedded content

Rich text fields deserve particular attention, since HTML content is often the most complex part of a migration.

I can't stress this point enough.

This is where the bulk of the audit and planning time will be spent for most migrations, especially when the existing content is coming from a legacy system such as Wordpress or Drupal.

Raw HTML content

The source content should be audited to check whether the destination system supports all the HTML tags and attributes actually in use.

Older systems tend to accumulate inline styles, legacy tags, and formatting quirks that newer platforms won't render the same way.

Any unsupported tags or attributes need a plan, whether that's conversion to a custom format that the new system understands, or removal.

Custom content embedded in HTML

Many older systems embed custom functionality directly inside HTML content, WordPress shortcodes being a common example.

These need to be identified separately from standard markup, since they represent functionality rather than formatting, and usually require bespoke conversion logic rather than a simple tag swap.

Media files

Binary media - images, PDFs, and similar files - needs its own audit pass, separate from the tabular data content.

Compatibility

The first question is compatibility: does the target system support the same media file types as the source?

Where it doesn't, a fallback plan is needed, such as dropping the corresponding links from HTML content rather than leaving broken references behind.

Import approach

The second question is one of approach: should media be pulled in directly via HTTP request at import time, or synced to the target's media storage in advance, with relations linked up during the import itself?

As a rough rule of thumb, fetching files on the fly tends to suit a small number of files, while pre-syncing to media storage works better at volume, since it avoids potentially thousands of live HTTP requests during the import run.

Building the migration scripts

With the audit complete, the technical build can begin.

A useful first step at the data model level is adding legacy ID and/or URL fields to the target system.

These act as a permanent reference back to the original record, which makes it possible to re-run imports, apply updates, and trace any given piece of migrated content back to its source.

From there, migration scripts are written for each data model involved - content types, taxonomies, media, and any other relational data identified in the audit.

Build migration scripts on existing toolsets

Using a tool such as django-import-export allows these to be built as deterministic and reusable import and export scripts, runnable from either the admin interface or the command line.

Import scripts should be written to handle both the initial data load and subsequent updates, matched against the legacy unique ID rather than assuming a one-time run.

Alongside these, helper scripts are needed to convert legacy source data into the target system's internal representations - for example, turning raw HTML links into internal id references to existing pages within the new system.

Writing automated unit tests

Whatever approach is taken for importing structured data, HTML, and embedded content, unit tests should be written alongside the migration scripts to confirm that the import, conversion, and removal logic all behave as expected.

Without automated testing, subtle mistakes can slip through unnoticed, since they're hard to spot by eye across thousands of pages.

Testing, dry runs, and the final content import

Before anything touches production, the full import process should go through a dry run, following the same import sequence it will use for real - media, then relational data, then content - to confirm each stage behaves as expected.

Errors found during dry runs, whether in the scripts themselves or in the exported tabular data, should be fixed and the import re-run.

This cycle repeats until the data is importing cleanly and consistently.

Once everything is verified, the final steps are to enact a full content freeze on the source system, make sure all tabular data exports are up-to-date, and then to run the final import into the target system.

Because the earlier exports were deterministic and repeatable, this last import run should be a formality rather than a surprise - the final run of a process that's already been tested many times over.

Any questions?

Wowsers, that was a long one.

If you feel you'd like more insight into how I think a migration should be done, then please do feel free to email me, I'm always up for a chat.