WordPress to Headless CMS: A Developer's Migration Guide

Why WordPress Export Doesn't Work

WordPress offers Tools > Export which creates a WXR (WordPress eXtended RSS) file. It's XML with:

• Multiple XML namespaces (wp:, dc:, content:, excerpt:)
• CDATA blocks wrapping content
• Encoded HTML inside XML
• Attachment references by ID
• Serialized PHP arrays for meta fields

Parsing this reliably is a project in itself. And most headless CMS platforms don't have native WXR importers.

What You Actually Need

For a typical Next.js or Gatsby migration, you need clean JSON like:

{
  "title": "My Post Title",
  "slug": "my-post-title",
  "content": "The post content in HTML or Markdown...",
  "excerpt": "Short summary...",
  "date": "2026-04-07T10:00:00Z",
  "author": "John Doe",
  "categories": ["Tech", "Tutorials"],
  "featuredImage": "https://example.com/image.jpg"
}

This structure can be directly consumed by any framework or imported into Contentful, Sanity, Strapi, etc.

Export Format Comparison

Format	Best For	Pros	Cons
JSON	APIs, headless CMS	Universal, structured	Not human-readable for long content
Markdown	Static generators, Git	Version control friendly	Loses some formatting
WXR (XML)	WordPress-to-WordPress	Complete data	Complex to parse

Migration Steps

1. Audit Your Content

Before exporting, understand what you have:

• How many posts/pages?
• What custom post types exist?
• What metadata do you need (ACF fields, SEO data)?
• How are images organized?

2. Choose Export Format

JSON for API-driven sites. Markdown if you're moving to a Git-based workflow or static generator.

3. Export Content

You can build a custom export script using WP_Query. But parsing Gutenberg blocks, handling shortcodes, and mapping fields correctly takes hours of debugging.

4. Handle Images

Options for images:

• Keep them on the original WordPress server (easiest)
• Download and re-upload to new CDN (cleanest)
• Search-and-replace URLs in exported content

5. Import to New Platform

Most headless CMS platforms can import JSON. Some have CLI tools for bulk imports. Structure your export to match their expected format.

Common Pitfalls

Shortcodes

WordPress shortcodes like [gallery] won't render in other systems. You need to either:

• Expand them to HTML before export
• Remove them and recreate functionality in the new system
• Convert to a portable format

Gutenberg Blocks

Gutenberg stores content as HTML comments with JSON data. A good export tool converts these to standard HTML or Markdown.

Internal Links

Links pointing to your WordPress URLs need updating. Plan for URL structure differences between platforms.

After Migration

Set up redirects from old WordPress URLs to new locations. Keep the WordPress site running temporarily in case you missed something.

Custom Script vs Export Plugin

Approach	Pros	Cons
Custom WP_Query script	Free, full control	Hours of coding, Gutenberg parsing is complex
WordPress native export	Built-in	XML format, hard to parse for other systems
Content Exporter	Clean JSON/Markdown, handles Gutenberg	$15 cost

If you don't plan your export properly: You'll spend days writing parsing scripts. Your Gutenberg blocks will export as HTML comments. Internal links will break. You'll discover missing metadata after you've already imported.