WordPress to Contentful Migration: A Composite Case Study

This is an illustrative composite. It does not describe any single real organization. The scenario, ranges, and details are generalized from patterns common to mid-market WordPress-to-Contentful projects so the lessons transfer without exposing any client.

Context

Picture a mid-market B2B software company: roughly 3,000–6,000 published URLs, a marketing site plus a busy blog and resource library, and a decade of WordPress accretion. Over the years the team had bolted on page builders (think a mix of shortcodes and a visual builder), a dozen plugins for SEO, forms, and redirects, and a theme that had been forked twice. Editors were productive but the front end was slow, security patching was constant, and every new campaign template required a developer.

The move to Contentful was driven by three things: a desire for a decoupled front end (a React/Next.js rebuild) to hit Core Web Vitals targets, structured content that could be reused across web, email, and an emerging mobile app, and governance — the CMO wanted content modeled once and syndicated, not copy-pasted. On paper it was a clean win. In practice, the first cut of the migration broke in ways that are entirely predictable once you have seen a few of these.

What broke

Redirects and URL structure

WordPress had been generating and storing redirects in a plugin's database table, not in a portable file. Nobody had a canonical export. The initial content sync moved posts and pages but silently dropped the several thousand accumulated 301s, plus the automatic redirects WordPress created every time a slug changed. On top of that, the new Next.js routing changed URL patterns — /blog/2019/03/post-title/ became /resources/post-title. Without a mapping, dated permalinks, ?p=123 query-string URLs, attachment pages, and paginated archive URLs all 404'd. Early crawls after the staging launch showed a meaningful share of previously indexed URLs returning errors.

Content model mismatches

The biggest surprise was that WordPress content is not structured — it is a blob of HTML in post_content. Page-builder layouts, inline styles, embedded shortcodes, and figure markup were all baked into that blob. Contentful expects clean, typed fields and references. The team's first model was too rigid (a single Rich Text field per page), which just re-imported the mess, and their second attempt was too granular (dozens of tiny content types) which editors hated. Shortcodes like [cta id="7"] and [gallery] came across as literal text. Embedded YouTube iframes, custom fields from ACF, and author bios stored in user meta needed bespoke transforms that the generic importer never touched.

Lost SEO and AEO signals

The SEO plugin had stored per-page titles, meta descriptions, canonical overrides, Open Graph data, noindex flags, and schema settings in post meta. None of that is visible in a standard WXR/XML export, so the first import shipped pages with auto-generated titles and no descriptions. Structured data (Article, FAQ, Breadcrumb, Organization) that the plugin had injected disappeared entirely, taking rich results and answer-engine eligibility with it. Canonical tags reset to self-referential defaults, which threatened to re-expose duplicate tag and category pages. Internal links written as absolute WordPress URLs now pointed at the dead domain path structure.

Taxonomy gaps

WordPress categories and tags are flexible to a fault. This site had 40+ categories, hundreds of tags, and heavy many-to-many tagging. Contentful models taxonomy explicitly — usually as reference fields to a topic or category content type. The import flattened tags into a comma-separated text field, breaking topic hub pages and faceted filtering. Hierarchical categories (parent/child) lost their nesting, and several tags were near-duplicates ("AI", "artificial-intelligence", "a.i.") that nobody had reconciled.

What worked

The recovery came from treating migration as a content transformation project, not a data copy. The team paused, exported everything to an intermediate format, and rebuilt in phases.

• A URL inventory first. They crawled the live site, pulled Search Console's top pages by clicks and impressions, and dumped the redirect table via direct database query. That produced a single mapping spreadsheet of old URL → new URL, prioritized by traffic and links.
• An editor-tested content model. They ran a card-sorting session with editors and settled on a mid-grained model: a handful of reusable components (Hero, RichText, CTA, MediaBlock, FAQ) composed on flexible page types. Shortcodes were parsed into these components programmatically.
• Meta migrated as first-class fields. SEO title, meta description, canonical, robots directive, and a structured-data type became explicit Contentful fields, populated from the extracted post meta and rendered by the front end.
• Taxonomy as references. Tags were deduplicated and mapped to a governed topic content type with defined parent relationships, restoring hub pages and filters.
• A staging crawl gate. No production cutover until a full crawl showed redirect coverage, correct canonicals, and no orphaned high-value pages.

Lessons

1. WordPress content is unstructured HTML. Budget most of your effort for parsing post_content, shortcodes, and page-builder markup into typed fields — not for the export itself.
2. SEO lives in post meta, not the export. Titles, descriptions, canonicals, robots flags, and schema settings must be extracted from plugin tables deliberately or they vanish.
3. Own your redirects before you touch anything. Export the redirect table, add slug-change history, and account for dated permalinks, attachment pages, feeds, and pagination.
4. Model with editors, not just developers. Too rigid re-imports the mess; too granular kills productivity. Aim for reusable mid-grained components.
5. Taxonomy is a data model, not a tag cloud. Deduplicate and map to references before import, or you lose hubs and faceted navigation.
6. Rebaseline expectations. A temporary ranking dip during recrawl is normal; the risk is permanent loss from unmapped URLs and missing signals.

The projects that go smoothly are the ones that inventory what exists before deciding where it goes. Pre-migration visibility is exactly the gap tools like Replatform Radar exist to close.

Before you make this move

• Export the full URL list plus Search Console top pages and the redirect table — reconcile into one mapping sheet.
• Extract SEO meta and structured data from plugin/database tables, not just the WXR file.
• Audit and deduplicate categories and tags; define the target taxonomy as Contentful references.
• Prototype the content model with two or three real, messy pages before bulk import.
• Write a shortcode/page-builder parsing map for every builder and shortcode in use.
• Rewrite internal links to relative paths during transform.
• Gate production cutover on a staging crawl that verifies redirects, canonicals, and no orphaned high-value URLs.
• Plan a post-launch monitoring window for 404s, crawl errors, and index coverage.

See more migration teardowns and checklists at replatformradar.com/migrate.