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:
- Export your WordPress content using the official WordPress export tool
- Send the export file to support@buttercms.com
- 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 support@buttercms.com 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:
- From WordPress admin, select Tools → Export
- Choose to export All content or select specific content types
- Click Download Export File
- 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:
- Email your WordPress export file to support@buttercms.com
- The ButterCMS team will import your content within 2-3 business days
- 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:
- Fetch WordPress content via WordPress REST API
- Transform data to match ButterCMS schema
- 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
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
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:
- Test everything - code, links, redirects, user logins
- Clone to production if using staging (contact Customer Support)
- Verify in production - double-check all functionality
- Check sitemap and RSS feeds
- Verify SEO - meta tags, structured data
- Monitor traffic - compare to previous performance
- Track success - revisit metrics after one month
