Skip to main content
Migrating from a specific platform? We have step-by-step guides for Contentful and WordPress.

​
When to consider migration

Before embarking on your migration journey, ask yourself these key questions:
  • Is your current CMS lagging? - Frequent errors, crashes, or difficulty implementing modern features
  • Is your system struggling to handle growth? - Slowdowns as you add content, storage limits, bottlenecks in workflows
  • Slow load times affecting user experience? - Pages taking more than a few seconds to load
  • Is your data lacking safety? - Security breaches, missing basic security features, unpatched vulnerabilities
  • You need more adaptability - Difficulty publishing across channels, can’t create/manage APIs, limited custom content types

​
The three phases of migration

Every successful content migration follows three essential phases:

​
Phase 1: planning

Your objective is to properly plan what needs to be migrated, how the migration will be performed, and how success will be verified. Key planning activities:
  1. Define migration goals - What do you want to achieve with the new CMS?
  2. Audit existing content - Create a complete inventory of pages, posts, media, and metadata
  3. Map content to ButterCMS - Identify how content will fit into Pages, Collections, and Blog Posts
  4. Identify dependencies - Links, references, categories, tags, authors
  5. Plan for SEO preservation - URL structure, redirects, meta tags
  6. Set acceptance criteria - How will you verify the migration was successful?
Below is an example content inventory for a hypothetical site using WordPress and how those items might map to ButterCMS. For information on the various content types, check out our core concepts article.

​
Content inventory template

​
Phase 2: execution

Once planning is complete, execute the migration:
  1. Execute and verify backup of your original site
  2. Disable crawlability during migration
  3. Execute test migration on a staging environment
  4. Verify all acceptance criteria on staging
  5. Perform the real migration of entire content inventory
  6. Enable the new site and restore crawlability
Never migrate directly to production first. Always use a staging environment to test and verify before going live.

​
Phase 3: Verification & monitoring

After migration, thorough verification is essential:
  1. Go through your acceptance criteria
  2. Manually test content for any overlooked issues
  3. Check performance and loading times
  4. Track SEO rankings and indexing
  5. Monitor analytics for any anomalies

​
Migration planning checklist

​
Pre-migration checklist

  • Define the goals of the migration
  • Back up the original site
  • Check deployment and rollback capability
  • Prepare analytics tracking for the new site
  • Complete list of URLs and internal links
  • Identify absolute vs relative URL references
  • Audit asset files and references
  • Review CMS-specific plugins to replicate
  • Document custom styling and content annotations
  • Identify interactive content requirements
  • Plan for popup and signup form migration
  • Plan migration of comments if applicable
  • Note character encoding requirements
  • Document original HTML tag structure
  • List categories and tags
  • Document SEO keywords
  • Plan table of contents migration for series
  • Document author information
  • Plan user data migration if applicable

​
Execution checklist

  • Execute and verify backup
  • Disable site crawlability
  • Run test migration on staging
  • Verify acceptance criteria on staging
  • Update DNS if changing domains
  • Perform full content migration
  • Enable new site
  • Restore crawlability

​
Post-migration checklist

  • Review all acceptance criteria
  • Manual content testing
  • Performance verification
  • SEO verification
  • Analytics monitoring
  • Retire or redirect old content

​
Minimizing migration risks

​
Risk assessment

Before beginning, conduct a thorough risk assessment:
  • Identify potential issues (data loss, functionality breakdowns, compatibility problems)
  • Analyze the impact each issue could have on your business
  • Create mitigation strategies for each risk

​
Pilot testing

Start small with a non-critical section:
  • Select a subset of content for initial migration
  • Document any issues encountered
  • Use learnings to inform full-scale migration

​
Fallback plan

Always have a contingency:
  • Maintain a fully functional version of your old CMS
  • Define clear rollback criteria
  • Document the rollback process

​
Regular backups

Implement a robust backup strategy:
  • Full site backups before major migration steps
  • Incremental data backups throughout the process
  • Regular testing of backup restoration

​
Setting migration goals

​
Define clear objectives

Ask yourself:
  1. Performance Goals - What load time improvements do you expect?
  2. Developer Experience - What technical capabilities do you need?
  3. Content Team Experience - How will the authoring workflow improve?
  4. Scalability Goals - What growth do you anticipate?
  5. Security Requirements - What compliance or security standards must you meet?

​
Establish success metrics

Define measurable targets based on your requirements. Here are example metrics to consider:

​
Timeline considerations

​
Typical migration phases

Break your migration into smaller milestones. This reduces risk and allows for course corrections along the way.