When moving to WordPress makes sense
Contentful is a strong headless CMS, but it is not always the right fit. Teams usually start looking at WordPress when the cost of seats and API usage grows, when every page change needs a developer because the front end is a custom application, or when editors want to preview and lay out pages themselves instead of filling in fields.
WordPress gives editors a visual block editor, a large ecosystem of plugins, and hosting options at every price point. The trade-off is that you take on its upkeep: updates, security, and performance. If your team mostly publishes pages, articles, and landing pages, that trade is usually worth it. If Contentful feeds several apps at once, the migration needs more planning, and keeping a headless setup with WordPress as the content source is an option worth weighing.
Step 1: Map the content model
Contentful organizes content into content types with fields, and entries reference each other. WordPress organizes content into post types, taxonomies, and custom fields. The first and most important step is deciding how each piece maps across.
- Content types become post types: pages and articles map to the built-in types, and the rest become custom post types.
- Fields become custom fields, usually with Advanced Custom Fields (ACF), or block attributes where editors should control the layout.
- Reference fields become relationships between posts, or taxonomy terms when the reference is really a category or tag.
- Rich Text fields become Gutenberg blocks. Contentful stores rich text as structured JSON, so each node type needs a rule: paragraphs, headings, lists, embedded entries, and embedded assets.
- Localized fields, if you use Contentful locales, need a plan for how each language will live in WordPress.
Write this mapping down as a table and get it approved before any code runs. Every later step depends on it, and changing it halfway through means redoing the imports.
Step 2: Inventory every URL and entry
Export a list of every published page with its URL, its content type, and its traffic from analytics or Search Console. Count the entries per content type and note anything unusual: very long pages, entries with many references, or content that is published but not linked from anywhere. The inventory becomes your checklist during validation and the basis for the redirect map.
This is also the moment to decide what not to migrate. Outdated pages with no traffic and no links can be retired, as long as each one gets a redirect to the closest relevant page.
Step 3: Export content and assets
The Contentful CLI can export a whole space, including content types, entries, assets, and locales, to a JSON file, and the Content Management API covers anything that needs a more targeted pull. Export more than once: an early export to build and test the import scripts, and a final export just before cutover, after a short content freeze so nothing published in Contentful is missed.
Assets need their own pass. Download every image and file, keep the original file names where possible, and record which Contentful asset became which WordPress media item, so references in rich text and fields can be rewritten.
Step 4: Transform and import
Import scripts read the export, apply the mapping from step one, and create content in WordPress through WP-CLI or the REST API. Rich Text JSON is converted node by node into block markup, embedded entries become the matching blocks, and links between entries are rewritten to their new WordPress URLs.
Make the import repeatable. It should be safe to wipe the staging site and run it again from scratch, because you will run it many times while fixing edge cases. Log every entry that fails or needs manual attention instead of skipping it silently.
Step 5: Preserve URLs, redirects, and SEO
Wherever possible, keep the same URLs. Where the structure has to change, create a 301 redirect from every old URL to its new one, using the inventory from step two. Carry over page titles, meta descriptions, social images, and canonical settings, which in Contentful often live in a separate SEO content type and are easy to forget.
Check the new site’s sitemap, robots settings, and structured data before launch. A staging site should block search engines, and launch day should remove that block. Leaving it in place is one of the most common reasons a site disappears from Google after a migration. The same checks apply to any website redesign.
Step 6: Validate before cutover
Validation is where a migration earns trust. Work through the inventory, not through impressions.
- Counts: the number of entries per content type in Contentful matches the number of posts per type in WordPress.
- Spot checks: compare a sample of pages side by side, including the longest and most complex ones.
- Links: crawl the staging site for broken internal links and missing images.
- Redirects: test every old URL from the inventory and confirm it returns a 301 to the right page.
- Editors: have the people who will use WordPress create and edit real content before launch.
Step 7: Cut over and watch
Cutover is usually a DNS change or a proxy switch scheduled for a low-traffic window, with the old site kept available for rollback. After launch, submit the new sitemap in Search Console, watch the indexing and not-found reports for a few weeks, and fix any redirect that was missed. Some ranking movement in the first weeks is normal; lasting losses almost always trace back to missing redirects or dropped content.
If you want help planning or running a migration like this, see my website migration service, or the Nielsen case study for related work building custom Gutenberg blocks.