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.

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:
// 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:

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.

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 .

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.