Content Import

EmDash imports content from WordPress and other platforms. Each import source detects a platform, analyzes its content, and fetches it into your site.

Import Sources

WXR File Upload

The most complete import method. Upload a WordPress eXtended RSS (WXR) export file directly to the admin dashboard.

Capabilities:

• All post types (including custom)
• All meta fields
• Drafts and private posts
• Full taxonomy hierarchy
• Media attachment metadata

How to get a WXR file:

WordPress.com OAuth

For sites hosted on WordPress.com, connect via OAuth to import without manual file exports.

What’s included:

• Published and draft content
• Private posts (with authorization)
• Media files via API
• Custom fields exposed to REST API

WordPress REST API Probe

When you enter a URL, EmDash probes the site to detect WordPress and show available content:

Detected: WordPress 6.4
├── Posts: 127 (published)
├── Pages: 12 (published)
└── Media: 89 files

Note: Drafts and private content require authentication
or a full WXR export.

The REST probe is informational. For complete imports, it suggests uploading a WXR file or connecting via OAuth (for WordPress.com).

Import Flow

All sources follow the same flow:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Connect   │────▶│   Analyze   │────▶│   Prepare   │────▶│   Execute   │
│  (probe/    │     │  (schema    │     │  (create    │     │  (import    │
│   upload)   │     │   check)    │     │   schema)   │     │   content)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Step 1: Connect

Enter a URL to probe or upload a file directly.

URL probing runs all registered sources in parallel. The highest-confidence match determines the suggested next action:

• WordPress.com site → Offer OAuth connection
• Self-hosted WordPress → Show export instructions
• Unknown → Suggest file upload

Step 2: Analyze

The source parses content and checks schema compatibility:

Post Types:
├── post (127) → posts [New collection]
├── page (12)  → pages [Existing, compatible]
├── product (45) → products [Add 3 fields]
└── revision (234) → [Skip - internal type]

Required Schema Changes:
├── Create collection: posts
├── Add fields to pages: featured_image
└── Create collection: products

Each post type shows its status:

Step 3: Prepare Schema

Click Create Schema & Import to:

1. Create new collections
2. Add missing fields with correct column types
3. Set up content tables with indexes

Step 4: Execute Import

Content imports sequentially:

• Gutenberg/HTML converted to Portable Text
• WordPress status mapped to EmDash status
• WordPress authors mapped to ownership (authorId) and presentation bylines
• Taxonomies created and linked
• Reusable blocks (wp_block) imported as Sections
• Progress shown in real-time

Author import behavior:

• If an author mapping points to an EmDash user, ownership is set to that user and a linked byline is created/reused for the same user.
• If there is no user mapping, a guest byline is created/reused from the WordPress author identity.
• Imported entries get ordered byline credits, with the first credit set as primaryBylineId.

Step 5: Media Import (Optional)

After content, optionally import media:

Media import uses content hashing (xxHash64) for deduplication. The same image used in multiple posts is stored once.

API Endpoints

The import system exposes these endpoints:

Probe URL

Detect the platform behind a URL with a probe request:

POST /_emdash/api/import/probe
Content-Type: application/json

{ "url": "https://example.com" }

The response contains the detected platform and suggested action.

Analyze WXR

Upload a WXR file to analyze its post types and schema compatibility:

POST /_emdash/api/import/wordpress/analyze
Content-Type: multipart/form-data

file: [WordPress export .xml]

The response contains the post type analysis with schema compatibility.

Prepare Schema

Create the collections and fields for the selected post types:

POST /_emdash/api/import/wordpress/prepare
Content-Type: application/json

{
  "postTypes": [
    { "name": "post", "collection": "posts", "enabled": true }
  ]
}

Execute Import

Import the content into the mapped collections:

POST /_emdash/api/import/wordpress/execute
Content-Type: multipart/form-data

file: [WordPress export .xml]
config: { "postTypeMappings": { "post": { "collection": "posts" } } }

Import Media

Download and store the media attachments referenced by the import:

POST /_emdash/api/import/wordpress/media
Content-Type: application/json

{
  "attachments": [{ "id": 123, "url": "https://..." }],
  "stream": true
}

The response streams NDJSON progress updates during download and upload.

Rewrite URLs

Replace old media URLs in imported content with their stored equivalents:

POST /_emdash/api/import/wordpress/rewrite-urls
Content-Type: application/json

{
  "urlMap": { "https://old.com/image.jpg": "/_emdash/media/abc123" }
}

Error Handling

Recoverable Errors

• Network timeout — Retried with backoff
• Single item parse failure — Logged, skipped, import continues
• Media download failure — Marked for manual handling

Fatal Errors

• Invalid file format — Import stops with error message
• Database connection lost — Import pauses, allows resume
• Storage quota exceeded — Import stops, shows usage

Error Report

After an import completes, EmDash shows a summary of what succeeded, what was adjusted, and what failed:

Import Complete

✓ 125 posts imported
✓ 12 pages imported
✓ 85 media references recorded

⚠ 2 items had warnings:
  - Post "Special Characters ñ" - title encoding fixed
  - Page "About" - duplicate slug renamed to "about-1"

✗ 1 item failed:
  - Post ID 456 - content parsing error (saved as draft)

Failed items are saved as drafts with original content in _importError for review.

Custom sources

To import from a platform the built-in sources do not cover, implement the ImportSource interface and register it on the integration:

import { mySource } from "./src/import/custom-source";

export default defineConfig({
	integrations: [
		emdash({
			import: { sources: [mySource] },
		}),
	],
});

The interface (probe, analyze, fetchContent) and the normalized output shape are documented in Architecture (internals).

Next Steps

• WordPress Migration — Complete WordPress migration guide
• Plugin Porting — Port WordPress plugins to EmDash