Migrate from WordPress
Use the EmDash admin to analyze a WordPress site, prepare compatible collections, import content, copy media, and rewrite URLs. Keep the WordPress site available until the imported site has passed verification.
Before you begin
Section titled “Before you begin”Prepare the following items:
- A backup of the WordPress database and
wp-content/uploads. - An EmDash site with storage configured if you plan to copy media.
- An EmDash administrator account. WordPress import requires the
import:executepermission. - Either a complete WordPress eXtended RSS (WXR) export or the EmDash Exporter plugin installed on the WordPress site.
Record the current permalink structure, canonical origin, redirects, menus, active post types, taxonomies, and any plugin-owned fields that the new site must preserve.
Choose an import method
Section titled “Choose an import method”| Method | Use it when | Included data |
|---|---|---|
| WXR upload | You can export from Tools → Export | Data represented in the export, including posts, pages, custom post types, taxonomy terms, menus, reusable blocks, authors, and attachment URLs |
| EmDash Exporter | You control the WordPress site and can install the exporter | Authenticated content plus supported site settings, SEO fields, taxonomies, and media metadata; comments, menus, the logo, and the favicon with exporter 1.2.0 or later |
Entering a site URL without the exporter only probes the public WordPress REST API. The probe can detect WordPress and count public posts, pages, and media, but it cannot perform a direct REST import.
Export a WXR file
Section titled “Export a WXR file”In WordPress, open Tools → Export, select All content, and download the XML export file. A WXR file points to media on the WordPress origin; it does not contain the attachment bytes.
Connect the EmDash Exporter
Section titled “Connect the EmDash Exporter”Check the exporter version on the WordPress Plugins screen. Comments, menus, the logo, and the favicon need exporter 1.2.0 or later. With an earlier version, the import completes without them and does not report them as missing.
With exporter 1.2.0 or later, open Tools → EmDash Migration in WordPress and generate a migration key. Paste the key into the EmDash import page.
With any exporter version, you can enter the WordPress site URL. When the exporter is detected, authorize EmDash through the WordPress application-password screen. When you open the EmDash admin on localhost or 127.0.0.1, enter the WordPress username and application password manually because the authorization callback requires HTTPS.
Import from a local WordPress site
Section titled “Import from a local WordPress site”EmDash connects to WordPress from its server and only to public addresses. It rejects localhost and private IP addresses, and it looks up hostnames in public DNS, so a name that exists only on your computer, such as mysite.local or mysite.test, does not resolve. This applies to the site URL, the exporter import, and the attachment downloads in the media step. For a site at such an address, the import page shows “Couldn’t detect WordPress”, and the media step can’t download the attachments of a WXR file exported from it.
To import from a WordPress site that runs on your computer, give it a public address for the duration of the import:
-
Start a tunnel to the port that your site’s own web server listens on. The following command starts a Cloudflare quick tunnel to a site on port 8080 and prints a public
trycloudflare.comaddress:Terminal window cloudflared tunnel --url http://127.0.0.1:8080Point the tunnel at the site’s port, not at its local hostname. In its default Site Domains mode, Local serves all its sites on port 80 and picks one by hostname, so a tunnel to
http://mysite.localgets Local’s “Site Not Found” page. Local also gives each site its own port, and a tunnel to that port reaches the site. Local lists that port in itssites.jsonfile (~/Library/Application Support/Local/sites.jsonon macOS), asservices.nginx.ports.HTTPin the site’s entry.Laravel Valet serves all its sites through one web server and picks one by hostname, with no port for each site, so these steps don’t work for Valet as written. Laravel Herd’s documentation describes reaching its sites only by hostname, so the same likely applies to Herd.
-
Make WordPress use the tunnel’s address and HTTPS. The tunnel forwards requests to WordPress over plain HTTP, and WordPress accepts application passwords only over HTTPS unless
WP_ENVIRONMENT_TYPEislocal. Add the following lines towp-config.php, above the “That’s all, stop editing!” comment, so that WordPress treats tunnel requests as HTTPS and puts the tunnel address in API responses and attachment URLs:wp-config.php if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {$_SERVER['HTTPS'] = 'on';}if (isset($_SERVER['HTTP_HOST'])) {$protocol = isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? 'https' : 'http';define('WP_HOME', $protocol . '://' . $_SERVER['HTTP_HOST']);define('WP_SITEURL', $protocol . '://' . $_SERVER['HTTP_HOST']);} -
Replace the site’s local address with the tunnel address in the WordPress database. Post content keeps each image at the address the site had when the image was inserted, and the media step rewrites only the image URLs that match an attachment’s address. The following
wp search-replacecommand replaceshttp://mysite.localwith a tunnel address. Replacehttp://mysite.localwith your site’s own address, which can differ from the address the tunnel points at, and the example tunnel address with the one the tunnel printed:Terminal window wp search-replace 'http://mysite.local' 'https://example.trycloudflare.com' --skip-columns=guidA quick tunnel gets a new address each time it starts, and an import keeps the addresses it read when it started. Keep the tunnel running until step 5. If it restarts before step 4, run the command again from the old tunnel address to the new one.
-
Use the tunnel address for the import: enter it as the site URL, generate the migration key from WordPress opened at that address, or download the WXR file from there so its attachment URLs point at the tunnel.
-
After the media step finishes, run
wp search-replaceagain with the two addresses swapped, remove the lines fromwp-config.php, and stop the tunnel. While the tunnel runs, anyone with the address can reach the site, including its login page.
Import through the admin
Section titled “Import through the admin”-
In the admin sidebar, select Import to open the Import from WordPress page, or visit
/_emdash/admin/import/wordpress. -
Upload the WXR file, paste the exporter migration key, or enter the WordPress URL.
-
Review the analysis. For each WordPress post type, confirm the target collection, required fields, and compatibility with any existing fields.
-
Map WordPress authors to EmDash users. An unmapped source author can be represented by a guest byline, so presentation credit does not depend on granting an EmDash login.
-
Choose whether to import menus. For an exporter import, also choose whether to import the site title and tagline, logo and favicon, and supported SEO values. These switches are not part of the WXR path.
-
Start the import. EmDash creates missing compatible collections and fields before it creates entries.
-
If attachments were found, run the media step. EmDash downloads the source bytes, stores them through the configured storage adapter, and rewrites matching content URLs.
Conversion behavior
Section titled “Conversion behavior”Statuses
Section titled “Statuses”The importer maps WordPress statuses as follows:
| WordPress | EmDash |
|---|---|
publish |
published |
draft |
draft |
pending |
draft |
private |
draft |
future with a date later than the import |
scheduled |
future with a past or missing date, trash, or an unknown status |
draft |
| Any status on a password-protected post (WXR import) | draft |
EmDash has no per-entry passwords. A WXR import brings in a password-protected post as a draft whatever its WordPress status, and the Import Complete screen lists each one. A password-protected future post with a date later than the import is not scheduled and has no publication date, so publishing it sets the current time. The EmDash Exporter does not send post passwords, so an exporter import maps a password-protected post by its status alone, and a published one arrives published.
WordPress visibility rules are not reconstructed from these statuses. Review every imported draft before publication.
Publication dates
Section titled “Publication dates”The admin importer preserves the source date for entries imported as drafts as well as published entries. Publishing an imported draft keeps that date, including when the draft came from a WordPress pending, private, or unrecognized status. This also applies to genuine WordPress drafts: if the source date is an old save date, first publishing the draft in EmDash backdates its publication date and any date-based permalink. Check the date before publishing.
The date source depends on the import method:
- WXR:
wp:post_date_gmt(UTC), thenpubDate(with its timezone), thenwp:post_date(site-local time). - EmDash Exporter:
date_gmt(UTC), thendate(site-local time).
The WordPress zero-date sentinel (0000-00-00 00:00:00) is skipped for GMT dates. A local date has no timezone information, so that fallback is approximate. If no usable source date exists, the draft has no publication date; publishing it sets the current time.
A WordPress future post with a date later than the import is scheduled rather than given a publication date immediately. Its publication date comes from its final schedule, so you can reschedule it or unschedule it and publish immediately. A future post with a date already in the past (a missed schedule) remains a draft and keeps that source date when published.
If an imported draft already has a publication date, scheduling it for later also keeps that date and its dated permalink. The schedule controls when it becomes visible, not its stored publication date. Edit the publication date separately if you want it to match the new schedule. This applies to genuine drafts and missed schedules.
These rules apply when creating entries during an import. They do not repair dates on previously imported entries; skipping existing entries on a retry leaves their dates unchanged.
Rich text and reusable blocks
Section titled “Rich text and reusable blocks”Gutenberg markup is converted to Portable Text. Classic HTML is processed by the same converter. Inspect complex blocks, embeds, shortcodes, page-builder markup, and plugin-defined blocks in the rendered EmDash site.
Blocks that WordPress renders on the server, such as Latest Posts or blocks from plugins, have no saved markup. They are imported as HTML blocks that contain the original block comment, for example <!-- wp:latest-posts {"postsToShow":3} /-->. These blocks show no content on the site. Open the block’s HTML tab in the editor to see what it was, then rebuild it or remove it.
WXR wp_block entries are imported as sections. They are not imported into an ordinary content collection.
Collections and fields
Section titled “Collections and fields”The default post-type mappings include post to posts and page to pages. Custom post types use a sanitized collection slug. The prepare step adds the standard title, Portable Text content, excerpt, and featured-image fields that the analysis requires.
Existing fields with compatible types are reused. A type mismatch blocks that collection mapping; the importer does not coerce an existing field to another type.
Custom fields and SEO data
Section titled “Custom fields and SEO data”WXR analysis reports non-internal post-meta keys and suggests field names and types, but the WXR database import writes the standard imported fields rather than copying every arbitrary meta key. Treat the analysis as a checklist for fields that may need a separate conversion.
The EmDash Exporter path can copy custom meta and Advanced Custom Fields (ACF) values when the target collection has matching fields. For an ACF field group with a “Post Type is equal to” location rule, the analysis suggests a field for every ACF field in the group: text, number, and true/false fields get matching types, and select, checkbox, repeater, group, relationship, and other fields that can hold a list or an object become JSON fields. Fields of groups assigned by other location rules are suggested only from the meta keys that the exporter reports. A collection whose fields an earlier import created from the meta keys keeps them, so its repeaters arrive as one field per row and sub-field. JSON values keep their WordPress shape: relationship, post object, user, and taxonomy fields point to WordPress posts, users, and terms by their WordPress IDs rather than to EmDash entries, and image, file, and gallery fields point to the WordPress media files rather than imported EmDash media. ACF group sub-fields stored on more than one post can also appear as separate fields next to the group’s JSON field; keep the copy your templates use. Review these values before using them in templates.
The exporter path can also create and populate the supported featured-image and Yoast or Rank Math SEO fields when their import switches are enabled.
Authors and bylines
Section titled “Authors and bylines”A mapped WordPress author becomes the entry owner. Presentation credits use bylines. If no user mapping exists, EmDash creates or reuses a guest byline based on the WordPress author identity.
Taxonomies
Section titled “Taxonomies”Categories and tags are imported into the matching EmDash taxonomy definitions. The exporter path can create definitions for custom taxonomies. A WXR custom taxonomy without a matching EmDash definition is reported as missing and its assignments are skipped.
Media deduplication compares a SHA-1 hash of the downloaded bytes. An existing media row with the same hash is reused. Filenames and WordPress IDs are not the deduplication key.
The source site must remain reachable at a public address while EmDash downloads attachments. For a site on your computer, see Import from a local WordPress site. Redirects from an attachment URL are validated before they are followed.
Retry a partial import
Section titled “Retry a partial import”The admin import is designed to skip existing entries, but its matching boundary matters:
- Existing content is matched by collection, slug, and locale, not by WordPress ID.
- If a source slug changed between attempts, inspect both entries and resolve the duplicate manually.
- Rerunning the media step reuses already stored byte-identical files by content hash.
- The exporter flow sends bounded chunks. Restarting the browser flow reruns content pages and rebuilds relationship maps from skipped entries.
The admin does not persist a WXR resume file. The --resume flag on emdash import wordpress belongs to a separate CLI workflow that writes converted JSON files to disk; it does not resume an admin database import.
Verify before cutover
Section titled “Verify before cutover”Check the imported site against the source:
- Count entries by post type and status.
- Open representative Gutenberg, Classic Editor, shortcode, and page-builder content.
- Confirm featured images and inline media resolve from EmDash URLs.
- Check authors, bylines, categories, tags, custom taxonomies, and translations.
- Test menus. After an exporter import, also test comments, site identity, and SEO fields.
- Crawl old public URLs and prepare redirects for every changed route.
- Verify drafts remain inaccessible to logged-out visitors.
Keep the backup and WordPress deployment until the new site has run successfully in production and rollback is no longer required.
Troubleshooting
Section titled “Troubleshooting”The XML file cannot be parsed
Section titled “The XML file cannot be parsed”Export the file again from Tools → Export and confirm the download completed. Do not edit the XML with a tool that changes its encoding.
A collection is marked incompatible
Section titled “A collection is marked incompatible”An existing field has the same slug but a different type. Change the post-type mapping or reconcile the field under Content Types before retrying. The prepare step adds missing fields but does not change existing field types.
Bot protection blocks the exporter
Section titled “Bot protection blocks the exporter”Cloudflare’s bot protection can answer EmDash’s requests with a challenge page instead of the exporter API. EmDash then reports that bot protection blocked the connection. Let the exporter requests through for the duration of the migration:
-
With Super Bot Fight Mode or other Cloudflare WAF features, add a custom rule with the Skip action and place it above any rule that issues challenges. Select All Super Bot Fight Mode rules, and Security Level if the zone uses I’m Under Attack mode. This expression matches the exporter API with and without pretty permalinks, including WordPress installs in a subdirectory, and the media files EmDash downloads:
(http.request.uri.path contains "/wp-json/emdash/v1/")or (http.request.uri.query contains "rest_route=%2Femdash%2Fv1%2F")or (http.request.uri.path contains "/wp-content/uploads/") -
Bot Fight Mode on the Cloudflare Free plan can’t be skipped by rules. Turn it off during the migration and turn it back on afterwards.
Media URLs fail to download
Section titled “Media URLs fail to download”Check that the source attachment is reachable without a WordPress session. Media behind authentication, removed files, and redirects to private network addresses fail individually and remain in the media error list.
Adapt the theme
Section titled “Adapt the theme”Use getEmDashCollection() for archive routes and getEmDashEntry() for a slug route. entry.id is the route identifier and is normally the slug; entry.data.id is the stored content ID used by relationship helpers.
The following route renders an imported post:
---import { decodeSlug, getEmDashEntry } from "emdash";import { PortableText } from "emdash/ui";
const slug = decodeSlug(Astro.params.slug);if (!slug) return Astro.rewrite("/404");
const { entry: post, error } = await getEmDashEntry("posts", slug);if (error) return new Response("Could not load the post", { status: 500 });if (!post) return Astro.rewrite("/404");---
<article> <h1>{post.data.title}</h1> <PortableText value={post.data.content} /></article>Read Porting WordPress themes for route and component mapping. Read Content import for the endpoint contracts and exact retry boundaries.