WordPress to ButterCMS migration

Migrate from WordPress to ButterCMS: export content, map posts and custom fields, preserve SEO, and handle enterprise considerations.

Why migrate from WordPress?

Common WordPress limitations

Limitation	Impact	ButterCMS Solution
Theming constraints	Limited design flexibility, changes lost on updates	Complete frontend freedom with any framework
Complex URL routing	Difficult custom routing implementation	Clean API-driven content delivery
Hosting & scaling	High-stakes hosting decisions, manual scaling	Fully managed infrastructure with auto-scaling
Performance	Monolithic architecture slows as traffic grows	Decoupled architecture with global CDN
Security	Constant vulnerability patching needed	Enterprise-grade security built-in
PHP-only	Limited to PHP for backend customization	Use any technology stack you prefer

Migration overview

ButterCMS provides assisted WordPress migration for blog content. The process is straightforward:

1. Export your WordPress content using the official WordPress export tool
2. Send the export file to [e-mail]
3. ButterCMS team imports your content within 2-3 business days

Enterprise customers can receive full site migration assistance including custom content types, complex data transformations, and dedicated migration support. Contact [e-mail] to learn more.

Step-by-step migration process

Step 1: Evaluate WordPress plugins

Before migrating, inventory your WordPress plugins and identify what needs to be replicated:

Backend plugins ButterCMS handles natively:

• SEO plugins (Yoast, etc.) → Built-in SEO fields
• Scheduling plugins → Native scheduling
• Localization plugins → Built-in localization
• Caching plugins → Global CDN caching
• Security plugins → Enterprise-grade security
• Backup plugins → Daily backups included

Frontend plugins requiring code:

• Custom forms → Implement in your frontend
• Social sharing → Add to frontend templates
• Comments → Integrate third-party service (Disqus, etc.)
• Analytics → Standard analytics integration

Step 2: Export WordPress content

Export your WordPress content using the official export tool:

1. From WordPress admin, select Tools → Export
2. Choose to export All content or select specific content types
3. Click Download Export File
4. The downloaded .zip contains XML export files

Important: Disable all plugins when exporting content to avoid plugin-specific notation in your export file that may cause issues during import.

Step 3: Send export to ButterCMS

For blog content migration:

1. Email your WordPress export file to [e-mail]
2. The ButterCMS team will import your content within 2-3 business days
3. Your content will be available in the ButterCMS Blog Engine

Note: Your ButterCMS account must be active with a paid subscription (Basic plan or higher) before the import can begin. View current plans.

Step 4: Set up custom content types

After blog content is imported, set up additional content structures:

Blog Engine comes with built-in fields:

• Title, body, summary, featured image
• SEO fields (meta title, description)
• Categories, tags, author
• Publication date, status

Page Types for custom pages:

• Landing pages with custom schemas
• Product pages with specific fields
• Team member profiles
• Case studies or portfolios

Collections for reusable data:

• Categories and taxonomies
• Team members and authors
• Testimonials
• FAQs
• Navigation menus

Step 5: Map WordPress content to ButterCMS

WordPress Content	ButterCMS Equivalent	Notes
Posts	Blog Posts or Page Type	Use Blog Engine for standard blogs
Pages	Single Pages or Page Types	Page Types for repeatable structures
Categories	Blog Categories or Collection	Blog Engine has built-in categories
Tags	Blog Tags or Collection	Blog Engine has built-in tags
Custom Post Types	Page Types	Create matching schema in ButterCMS
Custom Fields (ACF)	Page Type Fields	Map field-by-field
Media Library	Media Library	Automatic CDN hosting
Users/Authors	Blog Authors or Collection	Built-in author system for blogs
Menus	Collections	Model as navigation collection
Widgets	Components	Create reusable components

Step 6: Use Write API for custom migration

For content beyond basic blog posts, use the Write API to programmatically migrate:

1. Fetch WordPress content via WordPress REST API
2. Transform data to match ButterCMS schema
3. Post to ButterCMS using Write API

// Example: Fetch WordPress posts and create ButterCMS pages
const wpPosts = await fetchWordPressPosts();

for (const post of wpPosts) {
  const butterPage = {
    "page-type": "custom_post_type",
    status: "published",
    title: post.title.rendered,
    slug: post.slug,
    fields: {
      title: post.title.rendered,
      body: post.content.rendered,
      excerpt: post.excerpt.rendered,
      featured_image: post.featured_media_url,
      publish_date: post.date
    }
  };

  await fetch('https://api.buttercms.com/v2/pages/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Token ${WRITE_API_KEY}`
    },
    body: JSON.stringify(butterPage)
  });
}

Contact ButterCMS support to enable Write API access on your account.

Handling common WordPress features

Categories and tags

WordPress categories and tags map to ButterCMS in two ways:

Option 1: Blog Engine (Recommended for blogs)

• Categories and tags are built-in
• Automatically available in API responses
• Filter posts by category or tag

Option 2: Collections (For custom page types)

• Create “Category” and “Tag” collections
• Use Reference fields to link pages to categories
• Query by category using collection filters

Featured images

WordPress featured images can be migrated:

• Media files hosted on ButterCMS CDN
• Use Media field in your Page Types
• Images automatically optimized and served via CDN

Custom fields (ACF, etc.)

Map ACF fields to ButterCMS field types:

ACF Field Type	ButterCMS Field Type
Text	Short Text
Text Area	Long Text
WYSIWYG	WYSIWYG
Image	Media
File	Media
Gallery	Repeater with Media
True/False	Checkbox
Select	Dropdown
Date Picker	Date
Repeater	Repeater
Flexible Content	Component Picker
Relationship	Reference

Technical debt considerations

Common WordPress technical debt

Absolute URLs in content:

• WordPress often stores absolute URLs in content
• These break when changing domains
• Solution: Use find-and-replace during migration or post-process content

Plugin-specific shortcodes:

• Shortcodes like [ninja-inline=ID] won’t work after migration
• Identify and replace or remove during migration
• Plan frontend alternatives for critical functionality

Database-driven URLs:

• WordPress doesn’t use route-based routing
• Plan new URL structure that maps cleanly to ButterCMS
• Set up 301 redirects for SEO preservation

SEO preservation

SEO migration checklist

• Preserve URL structure or set up 301 redirects
• Migrate meta titles and descriptions
• Migrate Open Graph tags for social sharing
• Preserve canonical URLs
• Update XML sitemap to reflect new structure
• Submit new sitemap to Google Search Console
• Monitor rankings for 2-4 weeks after migration
• Check for 404 errors in Search Console

URL structure options

Approach	Example	Pros	Cons
Same URLs	/blog/my-post	No redirects needed	May require custom routing
New structure	/articles/my-post	Cleaner organization	Requires 301 redirects
Hybrid	Keep top pages, redirect others	Balances both	More complex setup

Enterprise migration considerations

For large WordPress installations:

Large data sets

• Release changes in small increments
• Use staging environment for testing
• Migrate in batches to reduce risk

Multisite WordPress

• ButterCMS supports multiple websites
• Migrate each site to a separate ButterCMS site
• Use Multisite dashboard to manage all sites

Testing environment

• Set up a staging environment in ButterCMS
• Test migration thoroughly before production
• Use environment switching for seamless deployment

Post-migration steps

After migration is complete:

1. Test everything - code, links, redirects, user logins
2. Clone to production if using staging (contact Customer Support)
3. Verify in production - double-check all functionality
4. Check sitemap and RSS feeds
5. Verify SEO - meta tags, structured data
6. Monitor traffic - compare to previous performance
7. Track success - revisit metrics after one month