How to Migrate from WordPress to a Headless Blog (Complete Guide)

A step-by-step walkthrough of moving your WordPress content to a headless blog platform. Covers REST API export, content model mapping, SEO preservation, and the one-click shortcut.

WordPress powers roughly 40 % of the web, but a growing number of bloggers, marketing teams, and developer publishers are migrating to headless architectures. The reasons stack up quickly: faster page loads, zero security patches, no plugin maintenance, and a content model that separates what you write from how it is displayed. If you have been researching headless CMS platforms and wondering how to get your WordPress content out without losing SEO traffic, this guide walks through every step.

We cover two paths. The first is the manual route — exporting via the WordPress REST API, mapping your content model, rebuilding the frontend, and setting up redirects. This is the approach you take when migrating to a generic headless CMS (Contentful, Strapi, Sanity, Storyblok) and it typically takes 4–8 weeks. The second is the automated route, where a purpose-built platform like Modern Blogging connects to your WordPress site's API and imports everything in about 60 seconds.

ℹ️

Headless blog vs traditional WordPress: In a traditional WordPress setup, PHP generates HTML on every page request. The theme, plugins, and database all run on the same server. In a headless setup, your content lives in a structured API or managed CMS, and a separate frontend — a static site generator, server-side rendered app, or edge-rendered page — builds the final HTML. The content and the presentation are decoupled. The blog you're reading right now runs on a headless architecture: content in Sanity, pages served from Cloudflare's edge network in under 200 ms.

Why bloggers are moving from WordPress to headless

The decision to migrate usually starts with one specific frustration, but once you look closely, the list grows:

Speed and Core Web Vitals

A typical WordPress install with an SEO plugin, a page builder, a caching plugin, analytics, and a contact form produces 3–5 second load times on shared hosting. Even on managed WordPress hosting (WP Engine, Kinsta, Flywheel), you are looking at 1.5–2.5 second Largest Contentful Paint scores. Google's Core Web Vitals threshold for "good" LCP is under 2.5 seconds, meaning most WordPress sites on shared hosting fail automatically.

A headless blog served from an edge CDN (Cloudflare, Vercel, Netlify) loads in under 200 ms because there is no server-side rendering on every request. Pages are pre-built or cached at the nearest edge location. There is no PHP execution, no database query, no plugin chain — just static HTML, CSS, and JavaScript delivered from the closest data center.

Security

WordPress is the most-attacked CMS on the web. Sucuri's annual hacked website report consistently shows WordPress accounting for over 90 % of cleaned CMS infections. Every plugin is an attack surface: a contact form plugin, a slider, an SEO tool — each one introduces PHP code that can contain vulnerabilities. Moving to a headless platform eliminates the entire attack surface. There is no PHP, no MySQL, no admin login page to brute-force, no xmlrpc.php to exploit. There is nothing to attack because there is no server-side application running on your domain.

Maintenance burden

WordPress sites require continuous maintenance: core updates, theme updates, plugin updates, PHP version upgrades, database optimization, backup configuration, and security monitoring. Since WordPress 5.5 (2020), automatic updates are available, but they can break SEO silently — a caching plugin update that serves stale noindex tags, a theme update that drops canonical tags, or a security plugin that starts blocking Googlebot. You often do not discover the problem until rankings drop weeks later.

A managed headless platform handles all infrastructure. You update nothing, patch nothing, monitor nothing. The platform team handles CDN configuration, SSL provisioning, image optimization, and uptime. You focus on content.

Content model and API access

WordPress stores everything as a "post" with metadata bolted on through custom fields. A headless CMS uses structured content — posts, pages, authors, categories as distinct document types with typed fields. This makes content portable and reusable: the same content can power a website, an email newsletter, an API, or an AI assistant . If you want to publish from a CI/CD pipeline, a GitHub Action, an AI agent, or a custom script, WordPress requires REST API plugins and workarounds. A headless platform exposes a native API that makes programmatic publishing a first-class workflow.

WordPress monolith vs headless architecture — single server PHP vs edge CDN with pre-built pages
How content delivery changes when you decouple the CMS from the frontend

Planning your migration: timeline, team, and scope

Before exporting a single post, plan the migration scope. The amount of work depends on what you are migrating and where you are going.

Migration type

Typical timeline

Team needed

When to choose

Simple blog → managed headless platform

1–2 hours

One person (you)

Content blog, standard post types, no custom plugin logic

Content site → generic headless CMS

4–8 weeks

Developer + content editor

Custom post types, ACF fields, complex taxonomy, custom frontend

E-commerce + blog → headless CMS + commerce

8–16 weeks

Development team

WooCommerce, membership plugins, complex integrations

For a straightforward blog (posts, pages, categories, images), the manual process is heavy but doable in a few weeks. The automated route with a purpose-built blogging platform takes under an hour. The decision is not about capability — it is about how much engineering effort the migration justifies.

What the WordPress REST API exposes

Every WordPress site running version 4.7 or later (released December 2016) exposes a REST API at /wp-json/wp/v2/ . This is the foundation of any headless migration — whether manual or automated. The API returns paginated JSON for every major content type:

Endpoint

Returns

Key fields

/wp-json/wp/v2/posts

All published posts

title, content (HTML), excerpt, slug, date_gmt, author (ID), featured_media (ID), categories (IDs)

/wp-json/wp/v2/pages

Static pages

title, content, slug, parent, menu_order

/wp-json/wp/v2/categories

Category taxonomy

name, slug, parent, description, count

/wp-json/wp/v2/tags

Tag taxonomy

name, slug, count

/wp-json/wp/v2/media

Uploaded images and files

source_url, alt_text, caption, mime_type, media_details (width, height, sizes)

/wp-json/wp/v2/users

Authors (public profiles)

name, slug, description, avatar_urls

The API returns 10 items per page by default (configurable up to 100 with the per_page parameter ). For a site with 200 posts, you would make 2–4 requests. The X-WP-Total and X-WP-TotalPages response headers tell you exactly how many items and pages exist.

The API returns rendered HTML in the content.rendered field, which includes the output of shortcodes and block editor blocks. This is the version you want for migration — it reflects what visitors actually see.

ℹ️

Custom post types and ACF fields: Custom post types and Advanced Custom Fields are accessible through the REST API only if registered with show_in_rest: true . Check your theme's functions.php or the ACF field group settings. If a custom post type does not appear in the API, add 'show_in_rest' => true to its registration arguments.

Path 1: Manual migration via REST API (developer route)

This is the approach described by Pagepro , AdaptoCMS , and Netguru . It works for any target CMS but requires development effort at every step.

Step 1: Audit your content

Before exporting anything, document what you have. This audit prevents surprises during import:

Step 2: Export via the REST API

Write a script that pulls all content from the WordPress REST API and saves it as JSON:

javascript
// Node.js: fetch all posts from a WordPress site
const BASE = 'https://your-site.com/wp-json/wp/v2';

async function fetchAll(endpoint) {
  let page = 1, items = [];
  while (true) {
    const res = await fetch(
      `${BASE}/${endpoint}?per_page=100&page=${page}`
    );
    if (!res.ok) break;
    const batch = await res.json();
    if (batch.length === 0) break;
    items.push(...batch);
    page++;
  }
  return items;
}

const posts      = await fetchAll('posts');
const pages      = await fetchAll('pages');
const categories = await fetchAll('categories');
const tags       = await fetchAll('tags');
const media      = await fetchAll('media');
const users      = await fetchAll('users');

console.log(`Exported: ${posts.length} posts, ${pages.length} pages, `
  + `${categories.length} categories, ${media.length} media items`);

// Save as JSON for the import step
import { writeFileSync } from 'fs';
writeFileSync('wp-export.json', JSON.stringify(
  { posts, pages, categories, tags, media, users }, null, 2
));

Save the exported JSON as your intermediate format. This is your migration artifact — you can re-run the export at any time, and you should re-run it right before the final cutover to capture any content published between your first test and go-live.

Step 3: Map your content model

The content model mapping is where the real engineering work happens. WordPress stores content as flat HTML with taxonomy relationships. A headless CMS uses structured document types:

WordPress

Headless CMS equivalent

Migration notes

post (HTML body)

Article type (structured text)

Convert HTML to the target format: Portable Text (Sanity), Rich Text (Contentful), Markdown (Ghost)

page

Page type

Preserve parent/child relationships if the CMS supports page trees

category

Category type (separate document)

Preserve slugs exactly for URL consistency

tag

Tag type or keyword array

Decide whether tags add value — many sites have hundreds of barely-used tags

featured_image (ID ref)

Image asset + reference

Download the image file, upload to the new CMS, store the new reference

post_meta (ACF/custom)

Custom fields on the document type

Map field-by-field — this is the hardest part because types may not have 1:1 equivalents

author (user ID)

Author type (separate document)

Create author documents first, then reference from posts

shortcodes

Custom blocks or components

Each shortcode needs individual treatment — there is no automatic conversion

Step 4: Import content

Import in dependency order to maintain references:

The import script should be idempotent — you can re-run it without creating duplicate content. Most headless CMS APIs support "create or replace" operations for this purpose.

Step 5: Rebuild the frontend

With content in the headless CMS, you need a frontend that fetches it and renders pages. This is typically a Next.js, Astro, or Nuxt app that:

This frontend development is the most time-consuming part of the manual migration — typically 2–4 weeks for a developer familiar with the target framework.

Step 6: Redirects and launch

Map every old URL to its new equivalent. This is the single most important step for SEO preservation. See our dedicated WordPress SEO migration checklist for the complete 25-step process. The key rules:

Migration timeline comparison — manual 4–8 week path vs automated 5-minute import
The time difference between manual and automated WordPress migration

Path 2: Automated import (Modern Blogging)

If your goal is a fast, SEO-optimized blog — not a custom web application — the 4–8 week manual process is disproportionate to the outcome. Modern Blogging's WordPress importer automates the entire flow: you paste your WordPress URL, the platform connects to the REST API, and imports everything in about 60 seconds.

How the automated import works

The entire process takes less time than Step 1 of the manual path. There is no scripting, no content model design, no frontend development, no DevOps configuration. The platform handles hosting, CDN, SSL, image optimization, SEO metadata, sitemaps, structured data, and the editor. You write posts and the platform does the rest.

ℹ️

What the automated import does NOT handle: WordPress shortcodes (they render to HTML during import, which is usually what you want), WooCommerce products (those need a commerce platform, not a blog platform), membership/paywall content, and custom plugin functionality. If your site relies heavily on these, the manual path to a generic headless CMS is the better choice.

Handling WordPress plugins during migration

One of the biggest sources of migration complexity is WordPress plugins. A typical blog has 15–30 active plugins. Here is how they map to a headless architecture:

Plugin category

Examples

In a headless platform

Action required

SEO

Yoast, Rank Math, AIOSEO

Built into the platform (meta tags, sitemaps, structured data, canonical URLs)

Export existing meta titles and descriptions; the platform generates the rest

Caching

WP Super Cache, W3 Total Cache, WP Rocket

Replaced by edge CDN — pages are cached globally without configuration

None — caching is automatic

Security

Wordfence, Sucuri, iThemes Security

No attack surface — no PHP, no MySQL, no admin login

None — there is nothing to secure

Image optimization

ShortPixel, Imagify, Smush

Automatic WebP conversion and CDN delivery

None — handled during import

Contact forms

WPForms, Gravity Forms, CF7

External service (Formspree, Typeform) or custom frontend

Replace with a form service and embed it

Analytics

MonsterInsights, GA plugin

Add tracking snippet in the platform settings or theme

Copy your GA4 measurement ID

Page builders

Elementor, Divi, Beaver Builder

Not applicable — the headless frontend replaces the theme entirely

Content from page builder sections needs to be converted to standard blocks

Social sharing

Social Warfare, AddToAny

Built into the theme or added as a frontend component

None or minimal frontend work

The pattern is clear: most WordPress plugins exist to compensate for limitations that a modern headless platform solves architecturally. SEO, caching, security, and image optimization are not plugins — they are infrastructure. Only contact forms and custom integrations typically need replacement services.

Protecting search rankings during migration

Migration-related SEO drops are caused by one thing: Google loses access to your content or sees conflicting signals about where it lives. Every SEO-safe migration follows the same principle — ensure that every URL Google knows about either stays the same or has a clear 301 redirect to its new location.

The pre-migration SEO baseline

Before changing anything, record:

This baseline is your "before" snapshot. After migration, you compare against it daily for the first week and weekly for the first month.

During migration

After launch

For the complete step-by-step process, our WordPress SEO migration checklist covers 25 items from pre-migration audit to 30-day post-launch monitoring.

WordPress REST API endpoints for migration — posts, pages, categories, media, users, and tags
Every WordPress site exposes these REST API endpoints for headless migration

Handling WordPress shortcodes, embeds, and Gutenberg blocks

One of the trickiest parts of any WordPress migration is dealing with content that is not pure text. WordPress posts often contain three types of non-standard content:

Shortcodes

Shortcodes are WordPress-specific placeholders that expand into HTML when the page renders. Common examples include [gallery], [contact-form-7], [embed], [woocommerce_cart], and theme-specific shortcodes like [pricing-table] or [testimonials]. The WordPress REST API returns the rendered HTML output of shortcodes in the content.rendered field, which is usually what you want — the gallery shortcode becomes a set of <img> tags, the embed shortcode becomes an iframe.

The exception is shortcodes from deactivated plugins, which appear as raw text (e.g., "[contact-form-7 id=123]"). Audit your content for these before migrating. Search your post content for the pattern \[.*?\] and verify that each shortcode rendered correctly.

oEmbed content

WordPress auto-embeds URLs from supported providers (YouTube, Twitter, Vimeo, Spotify, etc.) by converting them to iframes. The REST API's content.rendered field includes the fully rendered embed HTML. When importing to a headless CMS, you have two choices: keep the iframe HTML as-is (works but loses the ability to style or lazy-load embeds), or parse embeds during import and convert them to the CMS's native embed type.

Gutenberg blocks

Since WordPress 5.0 (2018), the block editor (Gutenberg) stores content as HTML with block-delimiter comments: <!-- wp:paragraph -->, <!-- wp:image -->, <!-- wp:heading -->. The REST API returns the rendered output without these delimiters, so basic blocks (paragraphs, headings, images, lists) migrate cleanly. Custom blocks and third-party blocks (from plugins like Kadence, GenerateBlocks, or Stackable) may produce complex HTML that needs manual review.

For most content blogs, the rendered HTML from the REST API is sufficient. Complex layouts, interactive blocks, and plugin-specific content are the exceptions that need manual attention.

Cost comparison: WordPress vs headless

The migration decision is partly financial. Here is what the ongoing costs look like:

Expense

WordPress (self-hosted)

WordPress (managed hosting)

Headless (managed platform)

Hosting

$5–30/mo (shared)

$30–115/mo (WP Engine, Kinsta)

$0–9/mo (free tier → Pro)

Domain

$10–15/year

$10–15/year

$10–15/year

SSL certificate

Free (Let's Encrypt) or $50–100/year

Included

Included (auto-provisioned)

SEO plugin

Free (Yoast) or $99/year (premium)

Free or $99/year

Built in, $0 extra

Image CDN

$0–50/mo (Cloudflare, BunnyCDN)

Often included

Built in (300+ edge locations)

Security plugin

Free or $99–299/year (Wordfence Pro)

Partially included

Not needed — no attack surface

Backup service

Free (UpdraftPlus) or $70/year

Included

Included (automatic)

Developer time

2–10 hrs/month maintenance

1–4 hrs/month

0 hrs/month

Estimated annual cost

$200–1,500+

$500–2,000+

$0–108 (free–Pro)

The biggest hidden cost of WordPress is developer time. Plugin conflicts, security patches, performance optimization, and debugging take hours every month. On a managed headless platform, that maintenance time drops to zero because there is nothing to maintain on your side.

Performance: WordPress vs headless (real numbers)

The performance gap between WordPress and a headless blog on edge infrastructure is measured, not theoretical:

Metric

WordPress (shared hosting)

WordPress (managed hosting)

Headless (edge CDN)

Time to First Byte

800–2,000 ms

200–500 ms

20–80 ms

Largest Contentful Paint

2.5–5.0 s

1.5–2.5 s

0.8–1.5 s

Total Blocking Time

200–600 ms

100–300 ms

0–50 ms

CLS (Layout Shift)

0.1–0.3

0.05–0.15

0–0.05

Server-side processing

PHP + MySQL per request

Cached but still PHP

None — pre-built pages

Global availability

One server location

1–3 data centers

300+ edge locations

Security patches

Weekly

Monthly (host handles some)

None

These numbers directly affect SEO. Google's Core Web Vitals are a ranking signal. The gap between "good" (LCP under 2.5s) and "needs improvement" (2.5–4.0s) is exactly where WordPress on shared hosting sits. A headless blog on edge infrastructure puts every page firmly in the "good" range without any optimization effort.

The performance advantage compounds with traffic. A WordPress site on shared hosting that gets a traffic spike (from a viral post, Hacker News, Reddit) will slow down or crash because each visitor triggers PHP execution and database queries. An edge-served headless blog handles traffic spikes without degradation because there is no backend to overload — every visitor is served from cache.

For more on how WordPress-specific issues affect search rankings, see our article on why WordPress blogs lose rankings .

Choosing the right headless platform

Not every headless CMS is a good fit for a blog. The right choice depends on your use case:

Use case

Best fit

Why

Content blog, no coding

Modern Blogging

One-click WordPress import, built-in SEO scorer, managed infrastructure, free tier

Custom app with blog section

Sanity, Contentful, Strapi

Full content modeling, custom frontend, headless API, maximum flexibility

Developer blog + community

Hashnode

Built-in developer community, custom domain, GitHub backup, GraphQL API

Newsletter-driven publication

Ghost (self-hosted)

Memberships, email newsletters, Handlebars themes — but you manage the server

Enterprise multi-channel content

Contentful, Storyblok

Multi-locale, multi-channel, approval workflows, enterprise SLAs

For detailed head-to-head comparisons, see Modern Blogging vs Ghost , Modern Blogging vs Hashnode , Modern Blogging vs WordPress.com , and Modern Blogging vs Substack .

Annual cost comparison — WordPress shared ($200–1,500), WordPress managed ($500–2,000), headless platform ($0–108)
Total cost of ownership for WordPress vs headless platforms

Eight migration mistakes that cost rankings

Frequently asked questions

Will I lose my Google rankings if I migrate?

Not if you handle redirects correctly. A well-executed migration with 1:1 URL mapping and proper 301 redirects preserves 95–99 % of link equity. Most publishers see rankings stabilize within 3–7 days and often improve within a month thanks to better Core Web Vitals. The risk comes from missing redirects, not from the migration itself.

Can I migrate a WordPress.com (hosted) site?

Yes. WordPress.com sites expose the same REST API at yourblog.wordpress.com/wp-json/wp/v2/. The import process is identical. If you are on a custom domain with WordPress.com, you can also point that domain to your new headless platform after migration. For a detailed comparison, see Modern Blogging vs WordPress.com .

What happens to my images?

During migration, all images referenced in your posts are downloaded from your WordPress site and re-hosted. On Modern Blogging, images are stored on Cloudflare R2 and served via a global CDN with automatic WebP conversion. Image URLs in your post content are rewritten to point to the new locations. If other sites link directly to your old image URLs (/wp-content/uploads/...), add redirects from the old image paths to the new ones.

How do I handle WordPress comments?

Most headless blog platforms do not include native commenting. If your blog relies heavily on comments, you have several options: migrate to a third-party system like Disqus or Commento (both can import WordPress comment exports), use Giscus (GitHub Discussions-based comments for developer blogs), or accept that comments are a low-value feature for SEO and skip them.

Can I go back to WordPress if the migration fails?

Yes. Keep your WordPress site running (on a different domain or subdomain) for at least 90 days after migration. If anything goes wrong, you can point DNS back to the WordPress server. This is standard practice — never decommission the old site until you have confirmed that the new site is fully indexed and traffic has stabilized.

How long does the migration take?

The automated route (paste URL → import) takes under 5 minutes including verification. The manual developer route takes 4–8 weeks depending on content complexity, custom post types, and the amount of frontend development needed. For a typical content blog with 50–200 posts and no custom post types, the automated path is the pragmatic choice.

Should you migrate? The decision framework

Migrate to headless if

Stay on WordPress if

For content blogs that want headless benefits without the multi-week engineering project, Modern Blogging is the shortest path: paste your WordPress URL, import in 60 seconds, and your blog runs on edge infrastructure with built-in SEO tools , a REST API , AI-native management via MCP , and AI-assisted content creation . Start free with up to 100 posts.


This article was written, styled, and published using the Modern Blogging platform. Launch your own fast, SEO-ready publication in minutes.

Share this post
𝕏in