How to Migrate from WordPress to EmDash: Step-by-Step Guide (2026)

Migrating your site from one platform to another is daunting. You’re worried about:

• Losing search rankings
• Breaking user experience
• Losing content or functionality
• Downtime

The good news: WordPress to EmDash migration is straightforward. The platform difference is huge, but the content migration is manageable. This guide covers both the DIY approach (if you’re technical) and when to hire a service.

Prerequisites

Before you start, you’ll need:

1. Access to your WordPress site (admin credentials, database access if going the DIY route)
2. A Cloudflare account (free tier is fine to start)
3. An EmDash project (created at https://emdash.io)
4. Basic familiarity with static site generation concepts (not required, but helpful)

Method 1: Using the EmDash WordPress Exporter (Recommended for DIY)

EmDash provides an official WordPress exporter plugin. This is the easiest path.

Step 1: Install the EmDash Exporter Plugin

1. Go to your WordPress admin dashboard
2. Navigate to Plugins → Add New
3. Search for “EmDash Exporter”
4. Click Install and Activate

Step 2: Export Your Content

1. Go to Tools → EmDash Export
2. Select the content types you want to export (posts, pages, custom post types)
3. Configure:
   • Export media files: Yes (recommended)
   • Include comments: Choose based on your needs
   • Export user data: No (you’ll recreate users in EmDash)
4. Click Generate Export
5. Download the .zip file

This creates a structured export of all your content, formatted for EmDash’s content collections.

Step 3: Prepare Your EmDash Project

1. Create a new EmDash project at https://emdash.io (or use existing)
2. Clone the project repository locally:

   git clone https://github.com/yourusername/your-emdash-project.git
   cd your-emdash-project
   

Step 4: Import the Content

1. Extract the WordPress export file
2. Copy the content files into your EmDash project’s src/content/ directory
3. Review the frontmatter (title, date, description, etc.) — EmDash uses YAML/TOML frontmatter
4. Ensure markdown formatting is correct (WordPress HTML exports need conversion)

Note: EmDash uses TypeScript content collections with Zod schemas. The exporter handles most of this, but you may need to manually adjust:

• Featured images (EmDash expects image paths, not URLs)
• Custom metadata
• Nested categories (EmDash uses tags, not hierarchical categories)

Step 5: Create 301 Redirects

This is critical for SEO. You need to redirect every WordPress URL to its EmDash equivalent.

In Cloudflare Pages:

1. Create a _redirects file in your public/ directory:

   /blog/old-post-slug /blog/new-post-slug 301
   /category/news /blog 301
   /2024/04/my-post /blog/my-post 301
   

2. Or use Cloudflare Workers for dynamic redirects (more flexible):

   export default {
     async fetch(request) {
       const url = new URL(request.url);
   
       // Redirect map
       const redirects = {
         '/old-url': '/new-url',
         '/blog/wordpress-post': '/blog/emdash-post',
       };
   
       if (redirects[url.pathname]) {
         return Response.redirect(redirects[url.pathname], 301);
       }
   
       return fetch(request);
     },
   };
   

Pro tip: Use the EmDash migration tools to auto-generate redirect maps from your WordPress export.

Step 6: Test on Staging

1. Build your EmDash project locally:

   npm install
   npm run build
   npm run preview
   

2. Verify:

   • All content is present
   • Images display correctly
   • Links work (including redirects)
   • Layout and styling look good
   • No console errors

3. Deploy to a staging environment on Cloudflare Pages:

   npm run build
   # Deploy to staging branch or separate domain
   

4. Test thoroughly in staging — this is where you catch issues before going live.

Step 7: DNS Cutover (Zero Downtime)

This is the moment of truth. You’re pointing your domain to EmDash.

Timing: Plan this for low-traffic hours (e.g., 2 AM on a Tuesday).

1. Verify Cloudflare Pages is set up:

   • Your domain’s DNS points to Cloudflare Pages
   • SSL certificate is provisioned
   • All pages load correctly in staging

2. Plan your cutover sequence:

   • Keep WordPress site running (don’t shut it down yet)
   • Update DNS to point to EmDash (TTL: 5 minutes)
   • Verify the new site is serving correctly
   • Keep monitoring for 30 minutes
   • After 30 minutes of stable traffic, you can decommission WordPress

3. During cutover:

   Old DNS: CNAME yoursite.com → wordpress-server.com
   New DNS: CNAME yoursite.com → yoursite.pages.dev
   

4. Update DNS records in your registrar (GoDaddy, Namecheap, etc.):

   • Point your domain’s CNAME to yoursite.pages.dev
   • Update MX records if you’re using email
   • Update other DNS records (SPF, DKIM, etc.)

5. Wait for propagation (usually 5-15 minutes, up to 48 hours in worst case)

6. Verify:

   # Check DNS resolution
   nslookup yoursite.com
   
   # Should return Cloudflare Pages IP
   # Should load correctly in browser
   

Method 2: Manual Export via WordPress XML (For Complex Sites)

If the exporter plugin doesn’t handle your setup, you can export manually.

Step 1: Export WordPress Data

1. Go to Tools → Export
2. Select “All content”
3. Download the .xml file (WXR format)

Step 2: Convert to EmDash Format

The XML format needs conversion to markdown. Use a conversion tool:

# Using npm package (example)
npx wordpress-to-markdown yoursite.xml --output ./src/content/blog

This outputs .md files with YAML frontmatter, ready for EmDash.

Step 3: Manual QA

You’ll likely need to:

• Verify markdown formatting
• Fix images paths
• Adjust custom fields
• Handle taxonomies (categories → tags)

This method takes longer but gives you more control.

Handling Special Cases

WooCommerce Stores

WooCommerce migration is more complex and is not yet covered by the current migration service. The EmDash e-commerce layer (shopemdash.com) is currently in development. Once available, it will enable full WooCommerce migrations including products, customer records, and order history.

In the meantime, if your site has a WooCommerce store, you have two options:

1. Migrate only the content/blog portion of your site now, and keep WooCommerce on a subdomain temporarily
2. Join the shopemdash.com waitlist to be notified when e-commerce migration is available

Custom Post Types

If you have custom post types (e.g., “Portfolio Projects”), you need to:

1. Map them to EmDash content collections:

   // src/content/config.ts
   const portfolio = defineCollection({
     type: 'content',
     schema: z.object({
       title: z.string(),
       description: z.string(),
       images: z.array(z.string()),
       projectLink: z.string(),
     }),
   });
   

2. Export the data and create corresponding markdown files

3. Update your templates to render the new collection

Multilingual Sites

If you have a multilingual WordPress site (using WPML or Polylang):

1. Export each language separately

2. Organize in EmDash using localized content collections:

   src/content/blog/
   ├── en/
   │   ├── post-1.md
   │   └── post-2.md
   └── fr/
       ├── post-1.md
       └── post-2.md
   

3. Configure Astro i18n routing to serve correct language version

Post-Migration Checklist

After your site is live, verify everything:

• All pages load without errors
• Images display correctly
• Links work (internal and external)
• 301 redirects are working (curl -I yoursite.com/old-url should show 301)
• Forms submit correctly
• Google Analytics tracks page views
• Search functionality works
• Mobile layout is responsive
• All features that existed before work now

Monitor for 30 Days

After going live, monitor closely:

1. Traffic metrics — Watch for drops in organic/referral traffic (there shouldn’t be any)
2. Search Console — Monitor for crawl errors or redirect chains
3. Error logs — Check for 404s or server errors
4. User feedback — Ask users to report issues

Most issues appear within the first week. By day 30, you can be confident the migration is stable.

When to Use the Professional Service

DIY migration makes sense if:

• Your site is simple (< 50 pages, < 200 posts)
• No custom plugins or post types
• You’re comfortable with technical tasks
• No WooCommerce or complex integrations

Use the professional service if:

• Your site is large (1000+ pages)
• You have custom plugins or post types
• You run WooCommerce
• You can’t afford downtime or issues
• You want guaranteed 30-day post-launch support

WP→EmDash handles:

• Complete content migration
• Design recreation (pixel-perfect if possible)
• All 301 redirects
• Staging validation
• Zero-downtime DNS cutover
• 30-day monitoring and support
• SEO preservation

Cost: $499 for simple sites, custom quotes for complex migrations.

Troubleshooting Common Issues

Images not loading after migration

Cause: Image paths are incorrect

Solution:

// In your Astro components, use correct image paths
import { Image } from 'astro:assets';

<Image src={import('../../images/my-image.png')} alt="..." />

Old URLs not redirecting

Cause: Redirect map is incomplete or misconfigured

Solution:

1. Test redirects: curl -I yourdomain.com/old-url
2. Verify _redirects file exists in public/
3. Check Cloudflare Workers script (if using)
4. Rebuild and redeploy

Google Search Console showing errors

Cause: Crawl issues during migration

Solution:

1. Go to Google Search Console
2. Submit your sitemap (Astro generates sitemap.xml automatically)
3. Mark URLs as “fixed” after verifying they work
4. Request re-indexing for critical pages

Performance not as expected

Cause: Unoptimized images or too much JavaScript

Solution:

• Use astro:assets for automatic image optimization
• Remove unnecessary JavaScript (EmDash defaults to zero JS)
• Use static generation for all content pages
• Verify Cloudflare caching is enabled

Conclusion

WordPress to EmDash migration is achievable, either DIY or with professional help. The key steps are:

1. Export your content (using the official exporter)
2. Import into EmDash content collections
3. Set up proper 301 redirects
4. Test thoroughly on staging
5. DNS cutover during low-traffic hours
6. Monitor for 30 days

The result: a faster, more secure, cheaper site with zero downtime.

Ready to get started? Get a free migration quote or reach out if you have questions.