Migrate from WordPress

EmDash provides a complete migration path from WordPress. Import your posts, pages, media, and taxonomies through the admin dashboard—no CLI required.

Before You Begin

Import Methods

EmDash supports three methods for importing WordPress content:

The WXR file upload is recommended for most migrations. It captures all content, including drafts, custom fields, and private posts.

WXR File Import

Content Conversion

Gutenberg to Portable Text

EmDash converts Gutenberg blocks to Portable Text, a structured content format.

Unknown blocks are stored as htmlBlock with the original HTML and block metadata. You can review and convert these manually or create custom Portable Text components to render them.

Classic Editor Content

HTML from the Classic Editor is converted to Portable Text blocks. Inline styles (<strong>, <em>, <a>) become marks on spans.

Status Mapping

Taxonomy Import

Categories and tags import as taxonomies with hierarchy preserved:

WordPress:                    EmDash:
├── Categories (hierarchical) ├── taxonomies table
│   ├── News                  │   ├── category/news
│   │   ├── Local             │   ├── category/local (parent: news)
│   │   └── World             │   ├── category/world (parent: news)
│   └── Sports                │   └── category/sports
└── Tags (flat)               └── content_taxonomies junction
    ├── featured                  ├── tag/featured
    └── breaking                  └── tag/breaking

Custom Fields and ACF

WordPress post meta and ACF fields are analyzed during import:

URL Redirects

After import, EmDash generates a redirect map:

{
	"redirects": [
		{ "from": "/?p=123", "to": "/posts/hello-world" },
		{ "from": "/2024/01/hello-world/", "to": "/posts/hello-world" },
		{ "from": "/category/news/", "to": "/categories/news" }
	],
	"feeds": [
		{ "from": "/feed/", "to": "/rss.xml" },
		{ "from": "/feed/atom/", "to": "/atom.xml" }
	]
}

Apply these redirects to:

• Cloudflare redirect rules
• Your hosting platform’s redirect config
• Astro’s redirects option in astro.config.mjs

Concept Mapping Reference

Use this table when adapting WordPress patterns to EmDash:

API Import (Advanced)

The WordPress import is available through the admin dashboard and the REST API. Use the admin dashboard import wizard for the best experience — it provides field mapping, conflict resolution, and progress tracking.

The import API endpoints are under /_emdash/api/import/wordpress/ for programmatic access.

Troubleshooting

”XML parsing error”

The export file may be corrupted or incomplete. Re-export from WordPress.

Media download failures

Some images may be behind authentication or have moved. The import continues, and failed URLs are logged for manual handling.

Field type conflicts

If an existing collection has a field with an incompatible type, the import wizard shows the conflict. Either:

• Rename the EmDash field
• Change the WordPress field mapping
• Delete and recreate the collection

Large exports

For exports over 100MB, consider:

1. Export post types separately in WordPress
2. Import each file sequentially
3. Use the CLI with --resume for reliability

Next Steps

• Content Import — Other import sources and methods
• Plugin Porting — Migrate WordPress plugin functionality
• Working with Content — Query and render your imported content