EmDash has a built-in WordPress import wizard — this isn't a manual copy-paste migration. It reads a standard WordPress export file, converts Gutenberg blocks to EmDash's structured content format, and preserves your taxonomy hierarchy, custom fields, and media. This walks through the exact process.

Before You Begin

• Export your content: in WordPress, go to Tools → Export and download a complete export file (.xml).
• Back up your site and keep WordPress running until you've verified the migration succeeded.

Choosing an Import Method

EmDash supports three import methods, and for most migrations, the WXR file upload is the right one — it captures everything, including drafts and private posts, with no authentication required:

• WXR file upload — best for complete migrations; includes drafts; no auth required.
• WordPress.com OAuth — best specifically for WordPress.com-hosted sites; includes drafts; requires OAuth.
• REST API probe — best for checking content before export; published content only; auth optional.

Step-by-Step: WXR File Import

1. Export from WordPress. In your WordPress admin, go to Tools → Export → All content → Download Export File.
2. Open the Import wizard. In EmDash, go to Admin → Settings → Import → WordPress.
3. Upload your export file. Drag and drop your .xml file or click to browse — it's parsed directly in your browser.
4. Review detected content. The wizard shows exactly what it found:

Found in export:
├── Posts: 127 → posts [New collection]
├── Pages: 12  → pages [Add fields]
└── Media: 89 attachments

1. Configure mappings. Toggle which post types to import — EmDash automatically creates new collections for unmapped post types, adds missing fields to existing collections, and warns about field type conflicts before you proceed.
2. Execute the import. Click Import Content and watch progress as each item processes.
3. Import media (optional). After content imports, choose whether to download media files — EmDash downloads from your WordPress URLs, deduplicates by content hash, and rewrites URLs in your content automatically.

Re-running the import is safe. Items are matched by WordPress ID, so you won't create duplicates.

What Happens to Your Content Structurally

Gutenberg Blocks Become Portable Text

EmDash converts Gutenberg blocks to Portable Text, a structured content format, preserving inline marks, heading levels, image references, list types, quote citations, code language attributes, and embed URLs. Blocks EmDash doesn't recognize are preserved as raw HTML for manual review rather than silently dropped.

Classic Editor Content

If your site still has Classic Editor (pre-Gutenberg) posts, that HTML converts to Portable Text blocks too, with inline styles like bold, italic, and links becoming marks on the corresponding text spans.

Status Mapping

WordPress statuses map directly to EmDash's equivalent states:

• publish → published
• draft → draft
• pending → pending
• private → private
• future → scheduled
• trash → archived

Taxonomy Hierarchy Is Preserved

Hierarchical WordPress categories import with their parent-child structure intact, and flat tags import as flat taxonomy terms — nothing gets flattened or restructured during the move.

Custom Fields and ACF

During the analysis phase, EmDash detects custom fields and infers appropriate EmDash field types from the actual values — numeric strings become `number`, `"1"`/`"0"`/`"true"`/`"false"` become `boolean`, ISO dates become `date`, and WordPress IDs like `_thumbnail_id` become `reference` fields. SEO plugin fields (Yoast, etc.) map into a dedicated `seo` object automatically. Internal WordPress fields prefixed `_edit_` or `_wp_` are hidden by default rather than cluttering your new schema.

ACF repeater fields and flexible content import as raw JSON — you'll want to create matching Portable Text or array fields in EmDash afterward to give that data proper structure rather than leaving it as opaque JSON.

Handling URL Redirects

After import, EmDash generates a redirect map so old WordPress URLs keep working:

{
  "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 this to Cloudflare redirect rules, your hosting platform's redirect configuration, or Astro's own `redirects` option in `astro.config.mjs` — skipping this step is the single most common cause of a real SEO ranking drop after a CMS migration, so don't treat it as optional.

Troubleshooting

"XML parsing error"

Your export file may be corrupted or incomplete — re-export from WordPress and try again.

Media download failures

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

Field type conflicts

If an existing EmDash collection has a field with an incompatible type, the wizard flags the conflict directly — rename the EmDash field, change the WordPress field mapping, or delete and recreate the collection.

Large exports (over 100MB)

• Export post types separately in WordPress rather than one giant file.
• Import each file sequentially instead of all at once.
• Use the EmDash CLI with `--resume` for reliability on very large migrations.

Frequently Asked Questions

Will my WordPress plugins and their functionality carry over?

Content and data from plugin fields generally import as custom fields, but plugin behavior itself doesn't transfer automatically. EmDash's plugin system is WordPress-inspired specifically to give custom functionality a defined porting path, but that's a separate step from the content import.

Is the import safe to run more than once?

Yes — items are matched by their original WordPress ID, so re-running an import after fixing a field conflict won't create duplicate content.

Do I need to take my WordPress site offline during migration?

No — the import reads from an export file (or probes via API), so your WordPress site can stay live and serving visitors throughout the entire migration and verification process.

What if some content doesn't convert cleanly?

Blocks EmDash doesn't recognize are preserved as raw HTML rather than lost, so you can review and manually convert them, or build a custom Portable Text component to render that specific HTML block type going forward.

The Bottom Line

EmDash's WordPress import is a genuine, guided migration path — not a manual re-entry project — handling posts, pages, media, taxonomies, custom fields, and redirects through one wizard. The most important step most teams skip is applying the generated redirect map; do that before flipping DNS. See our 10-minute EmDash setup guide if you haven't created your EmDash project yet.