How to Structure Your Drupal Website Content Migration


One of the most critical aspects of a Drupal CMS website redesign is migrating content to the new website. 

For some websites, the migration process can be quick and seamless if the new and old platforms are structurally similar or if there’s a limited amount of customizations. But some website redesigns require a significant amount of reformatting and revisions for content that needs to fit in new, complex layouts. In this case, the migration can be one of the most involved aspects of the build, requiring careful planning and execution.  

There are several considerations we underscore to clients for approaching content migration that is dictated by the new site design, new information architecture, and ease of site-building. 

The content migration structure we recommend the following includes:.

  1. Create a comprehensive list of pages.
  2. Determine whether you’ll do a programmatic migration or manual migration
  3. Clean up the content.

Let's dive right in.

1. Create a comprehensive list

It’s ideal to start with a shared spreadsheet of all pages you plan to migrate with separate columns for links (old and new), status (open, in progress, done), assignee, and notes highlighting questions, suggestions, or instructions (e.g. noting if a page needs copyediting, should be rewritten entirely, omitted, etc.). This is also a great time to review your meta titles and description and update them in accordance to on-site SEO best practices

Shared Google Sheets are incredibly useful for creating a comprehensive list since it’s a collaborative tool where users can correspond by commenting in cells using @useremail.

We recommend prioritizing the pages you’ll be migrating—starting with the highest priority (often some of the top-viewed pages on your website) and working your way down the list. With the context of the new design and/or build in mind, we strongly recommend reviewing and revising these pages accordingly so they’re as effective, up-to-date, and engaging as possible.

2. Determine the strategy (programmatic migration vs. manual migration)

For most migrations projects, the answer is it takes a little of both. For content that requires major revisions (grammar, formatting, inline styles) and/or is structurally different, we often recommend manual placement and find it is also a great way for the client’s editorial staff to get their feet wet in the new system or platform. 

Often the quickest way to migrate content is to have a small team in charge, instead of spreading it out among a lot of people. It prevents confusion over who’s doing what and makes content integration more consistent.

On many sites, there will be hundreds or thousands of pages that need to be migrated to keep an archive and/or provide SEO value as part of a website’s footprint. For pages you wish to omit, we strongly recommend implementing redirects for SEO value. Redirects can be added by any content editors directly in the new system, or, in a 301 redirect spreadsheet that Bear Group can implement at the server-level or programmatically in PHP.  

a look at drupal indexed links

During the audit and planning phase, we weigh the setup time involved when deciding to go with a programmatic migration over having a content manager conduct the migration by hand. Typically when a site’s page count gets upward of 200+ pages, some programmatic migration makes a lot of sense.

Drupal has a versatile migration system, the Migrate API, which allows for rollback and incremental updating of content between the old and new database. Incremental updates and rollbacks will allow content to be kept up to date right up until the new site goes live. Content identifiers retain their original values, making it easy to keep entity relationships intact. 

The Migrate API also provides basic scripts for migrating users, taxonomies, nodes, and additional methods for handling custom fields. In cases where Migrate API falls short, we use custom Drush migration scripts to handle mappings, fix body text formatting, or link old data structures to new ones.

Depending on the complexity of the build and the compatibility between the platform being migrated from to the platform being migrated to, programmatic tasks can take up to several weeks to plan, migrate, review, and polish.

3. Clean up content

Website redesigns provide a great opportunity to closely evaluate, revise, and restructure your page content to make improvements and factor in search engine optimization best practices when possible.

Use Google Analytics to identify pages getting the highest traffic to your website that you’ll want to pay close attention to in the process. Improving these high-traffic pages is a great starting point to keep people on your website longer and increase your ranking in search engines.

When making changes to the page copy itself, avoid doing a copy/paste directly from Word or PDFs into text area fields, since copying from these programs will often add in unwanted inline styles into your new site that can interfere with the front end presentation. 

For instance, sometimes deprecated font tags can be carried over in the html and on save, create visual inconsistencies on the front end.

an examples of inconsistencies in drupal code
Source HTML
an example of a correct drupal front-end
Front-end example


To avoid this, we recommend updating content directly in the CMS, using an editor toolbar that will provide site-specific styling options such as headings, button/links styles, and ordered lists.

Content strategy and migration is a topic that we love to discuss because there are always ways to improve the process and the better the content is, the more successful the website is, so feel free to contact us directly to discuss more!