How to Migrate a WordPress Site to EmDash

Migration questions are usually the most honest questions. You're not asking "is this CMS cool?" You're asking "can I actually get my stuff out of WordPress and into this thing without losing years of work?" That's a serious question, and it deserves a serious answer.

So here it is, as plainly as possible: migrating a WordPress site to EmDash is real, and it works, but it's not a one-click process. For a simple blog, it can take an afternoon. For a site with custom post types, ACF fields, and a heavily customized theme, you're looking at a more involved rebuild.

Note: EmDash launched in April 2026 and is currently in early beta (v0.1.0). The tools and steps below reflect the current state of the platform. Some rough edges exist, and we'll call them out as we go.

First: What actually migrates?

Before you touch any export button, it helps to know what EmDash can import and what it can't (yet).

What carries over cleanly:

Posts and pages (content, titles, slugs, publish dates)
Categories and tags (taxonomies)
Custom post types — with some mapping work
Custom fields / ACF data — with schema configuration
Media attachments (images, files)
Authors

What needs manual work:

Your theme (EmDash uses Astro, not PHP — a full rebuild is required)
WordPress plugins (no 1:1 equivalents; rebuilt as EmDash plugins in TypeScript)
Shortcodes (need to be converted or replaced before/after import)
Gutenberg blocks that rely on PHP or dynamic rendering
Comments (basic import may work, but verify post-migration)
Menus and widget configurations

What doesn't migrate (yet):

WooCommerce orders and product databases
Multisite networks
Membership plugin data (MemberPress, etc.)
Page builder layouts (Elementor, Divi, etc.)

Be honest with yourself about which category your site falls into. A straightforward blog migrates fast. A WooCommerce store with a custom Elementor theme is a full rebuild project, and no tool — for any CMS — is going to change that.

The two export paths

EmDash gives you two ways to get your content out of WordPress.

Option 1: Standard WXR export

WXR (WordPress eXtended RSS) is the built-in export format WordPress has used for years. It's an XML file that contains your posts, pages, custom fields, categories, tags, and navigation menus.

To export it:

In your WordPress admin, go to Tools → Export
Select All content
Click Download Export File

That's it. You'll get an .xml file. This works fine for straightforward sites, and EmDash's importer accepts it directly.

The catch: WXR files don't include media file bodies. Images are referenced by URL, not bundled inside the file. EmDash will attempt to pull those images during import, but for large sites or sites with a lot of media, this can be unreliable. More on this below.

Option 2: The EmDash Exporter plugin (recommended)

The EmDash Exporter plugin is a free, open-source WordPress plugin built specifically for this migration path. It does more than a standard WXR export.

What it adds on top of standard WXR:

Shortcode conversion maps — helps identify shortcodes that need handling
Theme settings including menus and widget structure
Custom field schema definitions in JSON format
Pre-defined field mapping for custom post types, so EmDash can auto-configure schemas on import

It also creates a secure API endpoint in your WordPress installation. Your EmDash instance can connect to this endpoint and pull content directly, rather than working from an intermediate file. For larger sites, this is much better — it streams content incrementally and supports multiple migration runs, so you can do trial imports and refine your mapping before committing.

To use it:

Install the plugin (upload manually or install from the wp-emdash GitHub repo)
Go to Settings → EmDash Export in your WordPress admin
Generate a WordPress Application Password for secure API access
Configure your export settings and generate both the WXR file and a JSON configuration file

Keep both files. You'll need them for the import step.

Setting up EmDash

If you haven't already, spin up an EmDash instance:

npm create emdash@latest

Follow the prompts, then start the local server and log into the admin panel. EmDash uses passkey authentication by default — no password setup needed.

If you're deploying to Cloudflare Workers (the native target), you'll want to have your Cloudflare account connected before the import. EmDash stores media in Cloudflare R2, Cloudflare's object storage service. That's where your imported images will land.

Mapping custom post types

This is where most of the real work happens for sites that go beyond standard posts and pages.

In WordPress, a custom post type (CPT) like portfolio, case-study, or product is just a registered post type with its own fields. In EmDash, the equivalent is a content type (also called a collection), defined by a schema.

Before you run the import, you'll need to:

Audit your custom post types. List every CPT on your WordPress site and the custom fields attached to each one (ACF groups, plugin-added meta, etc.)
Create matching schemas in EmDash. In the EmDash admin, define a content type for each CPT with fields that mirror your WordPress fields. The type mapping is roughly:
- text field → text
- image field → media
- repeater field → array
- relationship field → reference (may need manual linking post-import)
Run the import with type mapping. When importing your WXR file in EmDash, you'll see a mapping preview that lets you route each WordPress post type to the correct EmDash collection. If you're using the CLI, the --map-types flag handles this:

emdash import wordpress /path/to/export.xml

If you used the EmDash Exporter plugin, the JSON configuration file automates most of this schema mapping — another reason to use the plugin over a plain WXR export.

Media migration

Media is the part of WordPress migrations that quietly causes the most headaches, regardless of which CMS you're moving to.

The WXR file contains references to your media (URLs), not the actual files. When EmDash processes the import, it attempts to fetch and download each referenced file from your WordPress site's media library. This works well if:

Your WordPress site is still live during the import
Your media is hosted on your main WordPress domain (not a CDN with hotlink protection)
You don't have thousands of files

For sites with large media libraries (1,000+ images, videos, or PDFs), it's worth doing a direct media transfer alongside the import:

Download your wp-content/uploads folder via FTP/SFTP or your hosting panel
Upload the relevant files directly to your EmDash media library or Cloudflare R2 bucket before running the import
If URLs change, you'll need to do a find-and-replace pass on your content post-import (the EmDash admin has a content search tool for this)

Preserving URLs and SEO

This is the part that makes agencies nervous, and rightfully so. Changing URLs without redirects is one of the fastest ways to lose years of SEO equity.

Slugs: EmDash preserves post slugs during import. If your WordPress post lives at /blog/how-to-do-x, the slug how-to-do-x comes with it. Whether the full URL path matches depends on how you configure your EmDash theme's routing.

Permalinks and routing: WordPress URL structures (like /year/month/slug/ or /category/slug/) are controlled by your permalink settings and theme. In EmDash, routing is defined in your Astro theme. Match your EmDash routes to your WordPress structure and most URLs will preserve automatically.

Redirects: For any URLs that do change — and some will — set up 301 redirects. Since EmDash runs on Cloudflare Workers, you can handle redirects either in your EmDash configuration or directly via Cloudflare Redirect Rules in your dashboard. The latter is often easier for bulk redirects.

Meta and SEO data: If you were using Yoast SEO or Rank Math, your SEO titles and meta descriptions live in WordPress's post meta table and will come over with the WXR export. You'll need to map them to EmDash's SEO fields during import, or add them manually post-migration. EmDash has built-in SEO fields for each content type — no plugin required.

Sitemaps: EmDash generates sitemaps natively. Once your content is live, submit the new sitemap to Google Search Console and monitor for any crawl issues.

What about my theme?

There's no getting around this one. WordPress themes are PHP. EmDash themes are Astro. They are not compatible, and no automated conversion exists.

This is the "heavier lift" part of the migration that varies wildly depending on your site.

Simple blog? You can have a clean Astro theme running in a few hours, especially if you start from an EmDash starter theme.
Complex design with custom layouts, page builder sections, and dynamic components? That's a frontend rebuild. Budget time accordingly.

The honest position: if your WordPress theme is the main thing holding your site together (heavy Elementor builds, custom WooCommerce templates, etc.), the migration effort is mostly about rebuilding the frontend. The content import is the easy part.

Honest assessment: who should migrate now?

EmDash is genuinely promising, but it's in early beta. Here's a straight read on who's ready and who should wait.

Good fit for migrating now:

Blogs, editorial sites, and content-heavy sites with standard post types
Developer-led projects where the team is comfortable with TypeScript and Astro
Sites that are already frustrated by WordPress performance, plugin security, or hosting overhead
New sites that want to start on modern infrastructure and have historical WordPress content to bring over

Better to wait:

Sites that rely heavily on WooCommerce or any ecommerce functionality
Multisite networks
Sites built around page builders (Elementor, Divi, Beaver Builder)
Non-technical users who need a ready-made theme ecosystem (it's growing, but thin right now)
Anyone who can't tolerate some ecosystem immaturity — EmDash had 18 stars and 3 forks on its migration plugin repo as of launch week. WordPress has 60,000+ plugins. That gap is real.

The process, end to end

Here's the full migration flow in order:

Audit your WordPress site. List your content types, custom fields, plugins you depend on, and media volume.
Install the EmDash Exporter plugin in WordPress and generate your export (WXR + JSON).
Spin up EmDash with npm create emdash@latest.
Define your content type schemas in the EmDash admin before importing.
Run the import — upload the WXR + JSON files through the EmDash import UI.
Review the mapping preview and confirm custom post types route to the right collections.
Handle media — let the importer pull files during import, or transfer manually for large libraries.
Build or configure your Astro theme to match your URL structure.
Set up redirects for any URLs that changed.
Test everything — content, images, forms, SEO meta, sitemaps.
Update DNS to point your domain at your Cloudflare Workers deployment.
Submit your sitemap to Google Search Console and monitor crawl coverage.

Migration is never zero-effort, for any platform. But EmDash has built a real path from WordPress, and for the right site, it's worth the work. Have questions about your specific setup, or want help assessing whether your WordPress site is a good candidate for EmDash? Get in touch. We're happy to talk through it.