> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 [support@buttercms.com](mailto:support@buttercms.com)
3. **ButterCMS team imports** your content within 2-3 business days

<Info>
  **Enterprise customers** can receive full site migration assistance including custom content types, complex data transformations, and dedicated migration support. Contact [support@buttercms.com](mailto:support@buttercms.com) to learn more.
</Info>

## 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

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

### Step 3: Send export to ButterCMS

For blog content migration:

1. Email your WordPress export file to [support@buttercms.com](mailto:support@buttercms.com)
2. The ButterCMS team will import your content within 2-3 business days
3. Your content will be available in the ButterCMS Blog Engine

<Info>
  **Note:** Your ButterCMS account must be active with a paid subscription (Basic plan or higher) before the import can begin. [View current plans](https://buttercms.com/pricing/).
</Info>

### 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

```javascript theme={null}
// 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)
  });
}
```

<Tip>
  Contact ButterCMS support to enable Write API access on your account.
</Tip>

## 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