Skip to content

Content import

EmDash imports WordPress content through the Import from WordPress page at /_emdash/admin/import/wordpress. The importer can analyze a WordPress eXtended RSS (WXR) file or connect to a site running the EmDash Exporter plugin.

The source registry contains three WordPress sources:

Source ID Input Imports content Access
wxr WordPress export .xml file Yes Data present in the export
wordpress-plugin Site URL plus EmDash Exporter credentials Yes Exporter endpoints, including authenticated content
wordpress-rest Public site URL No Probe and public counts only

There is no wordpress-com OAuth import source. A WordPress.com site must use a WXR export or a compatible EmDash Exporter connection.

Use WXR when WordPress can export the content you need and the EmDash Exporter cannot be installed.

  1. In WordPress, open Tools → Export, select the required content, and download the XML file.

  2. In EmDash, select Import in the admin sidebar and upload the file.

  3. Review the detected post types, fields, authors, taxonomies, reusable blocks, and attachment URLs before creating schema or content.

The XML contains attachment metadata and source URLs, not the media bytes. Keep WordPress reachable at a public address until the optional media copy has finished. A site on your computer needs a tunnel, as described in Import from a local WordPress site.

Use the exporter when you control the WordPress site and need authenticated data such as drafts or supported settings. Comments, menus, the logo, the favicon, and the Tools → EmDash Migration page that generates a migration key need exporter 1.2.0 or later. Any exporter version can connect with a WordPress username and application password. The exporter sends data through its emdash/v1 API endpoints; it does not grant EmDash direct database access.

The admin performs these stages:

  1. Connect. Upload a WXR file, paste an EmDash Exporter migration key, or enter a site URL.
  2. Analyze. Read post types, required fields, authors, attachments, and schema compatibility.
  3. Review. Select post types, collection mappings, authors, and supported extras.
  4. Prepare. Create missing collections and fields. Existing fields with incompatible types block that mapping.
  5. Import. Convert and create content. The exporter path uses bounded content, comment, and finalization requests.
  6. Copy media. Download selected WXR attachments into EmDash storage and rewrite matching URLs.

The WXR path can import posts, pages, custom post types, taxonomies, menus, reusable blocks, authors or guest bylines, and media listed in the export. The exporter path can additionally fetch selected site settings and supported SEO values from the live WordPress API, and with exporter 1.2.0 or later also comments, the logo, and the favicon.

A WXR import creates each menu with its WordPress slug as the name that getMenu() looks up, and its WordPress name as the label. Each menu keeps its nesting, and its items link to the imported entries. An item without its own label shows the entry’s title, as in WordPress. An item that links to a post type archive links to the archive of the collection that the post type was imported into, and without its own label it shows the collection’s label. On a site translated with Polylang or WPML, each menu takes the language of the entries it links to. Items are skipped and counted in the import result when they link to a category or tag archive, to content the import left out, or to one of several pages that share a slug in the same collection and language, such as services/support and products/support. The import creates one entry for that slug, so it can’t tell which page the entry stands for. A Polylang language switcher in a menu is skipped and counted too: Polylang replaces it with the language links when it shows the menu, so the export holds only a placeholder. To offer the same choice on the new site, build a language switcher in your templates. A menu that already exists with the same name and language is left unchanged.

For each detected post type, the review screen shows the suggested collection and one of four schema states:

State Meaning
Ready The collection and required fields already have compatible types
New collection The prepare step will create the collection and its required fields
Add fields The collection exists and the prepare step will add missing fields
Incompatible An existing field has a different type; fix the mapping or schema before importing that post type

The prepare step is additive. It does not change the type of an existing field to make an import fit.

The content routes store two statuses from a WordPress import:

WordPress status EmDash status
publish published
draft draft
pending draft
private draft
future, trash, or another value draft
Any status on a password-protected post (WXR import) draft

The importer does not preserve WordPress pending, private, scheduled, or trash semantics. Review those entries before publishing them in EmDash.

The WXR and exporter sources convert Gutenberg markup to Portable Text. They map post to posts, page to pages, and known custom post types to collection slugs. Internal WordPress post types are excluded. Reusable blocks (wp_block) are handled as EmDash sections rather than ordinary entries.

For an imported entry:

  • The WordPress post slug becomes the EmDash slug when available.
  • EmDash generates its own database ID.
  • Author mappings attach an EmDash user. An unmapped WordPress author can become a reusable guest byline.
  • WordPress IDs are used transiently to resolve relationships such as menus, comments, featured images, and translations. They are not the persistent identity used to detect an existing WXR entry.

WXR reruns with skipExisting match an existing entry by collection, slug, and locale. A changed slug can therefore create another entry. The exporter path uses the same slug-and-locale check and rebuilds its WordPress-ID relationship map from entries that it skips.

The media stage downloads each attachment URL, computes a SHA-1 hash of the downloaded bytes, and looks for an existing media row with that content hash. Identical bytes reuse the existing media record even when the WordPress URLs differ.

The hash is stored with a sha1: prefix. It is a deduplication key, not a security signature. Two URLs are not treated as duplicates merely because their filenames match.

After copying media, the importer rewrites matching URLs in Portable Text, text, string, image, and file fields. Keep the WordPress origin online until downloads and rewritten pages have been verified.

The admin does not store a durable resume token for a WXR import. If a request fails:

  • Rerun the analysis and import with skip existing enabled.
  • Existing entries are skipped by collection, slug, and locale.
  • Rerunning media is safe for files that were already stored because byte-identical downloads reuse the content hash.
  • Inspect partial schema changes and entries with changed slugs before retrying.

The exporter flow is chunked to fit Worker limits. The browser carries cursors and WordPress-to-EmDash relationship maps between requests. If the browser loses that state, restart the import; skipped entries rebuild the relationship map as the content pages are processed.

The separate emdash import wordpress CLI writes converted JSON files to an output directory. Its --resume option reads .wp-migration-progress.json and skips WordPress post and attachment IDs already recorded there. That file-conversion workflow is not the admin database import and does not make admin requests resumable.

These endpoints power the authenticated admin page. They require an admin session with import:execute and the X-EmDash-Request: 1 header. Success responses normally use the envelope { "success": true, "data": ... }; errors use { "success": false, "error": { "code", "message" } }.

POST /_emdash/api/import/probe accepts JSON { "url": "https://example.com" }.

Its data value is { success: true, result }. result contains url, isWordPress, bestMatch, and allMatches. A plain WordPress REST match recommends a WXR upload; it does not enable direct REST import.

POST /_emdash/api/import/wordpress/analyze accepts multipart/form-data with a file part. Its data value contains the site, post-type analysis, attachment summary, author summary, taxonomy counts, and custom-field suggestions.

POST /_emdash/api/import/wordpress/prepare accepts this JSON shape:

Request body
{
"postTypes": [
{
"name": "post",
"collection": "posts",
"fields": [
{
"slug": "title",
"label": "Title",
"type": "string",
"required": true,
"searchable": true
}
]
}
]
}

Its data value contains success, collectionsCreated, fieldsCreated, and per-collection errors.

POST /_emdash/api/import/wordpress/execute accepts multipart/form-data with:

  • file: the WXR file.
  • config: a JSON string containing postTypeMappings, skipExisting, optional authorMappings, optional importSections, and an optional import-wide locale.

Its data value contains success, imported, skipped, errors, byCollection, and optional section and taxonomy summaries. When the request imports password-protected posts, data also contains passwordProtected, which lists each one as { id, collection, title }.

POST /_emdash/api/import/wordpress/media accepts JSON { "attachments": [...], "stream": true }. Streaming is the default. A streaming response is newline-delimited JSON with progress records followed by one result record; it does not use the normal API envelope. Set stream to false to receive the normal envelope around { imported, failed, urlMap }.

POST /_emdash/api/import/wordpress/rewrite-urls accepts JSON { "urlMap": { "old": "new" }, "collections": ["posts"] }. The optional collection list limits the rewrite. Its data value contains updated-entry and rewritten-URL counts plus errors.

POST /_emdash/api/import/wordpress-plugin/analyze accepts JSON { "url", "token" }, where token is a Base64 Basic Authentication value for a WordPress user and application password. Its data value is { success: true, analysis }.

POST /_emdash/api/import/wordpress-plugin/execute accepts JSON with url, token, and config. The admin also supplies a phase (content, comments, or finalize). Each response contains done, an optional next cursor, a partial result, and a chunk object with any updated idMap, translationGroups, or commentRoots. The admin merges the chunk values and sends the accumulated maps with the next request.

The site is detected but cannot import directly

Section titled “The site is detected but cannot import directly”

A wordpress-rest result is a probe only. Upload a WXR file or install the EmDash Exporter and probe the site again.

Expand the post type in the review screen to find the conflicting field. Change the target collection or reconcile that field in Content Types. The importer will not replace an existing field type.

The final media result lists failed source URLs. Confirm that each URL is public, still exists, and does not redirect to a private network address. Retry the media step after fixing access; completed byte-identical files will be reused.