How to move a WordPress site to EmDash, and what broke when we did

On 2 November 2026 we moved a test WordPress site to EmDash 1.4.0. The WordPress 7.1.4 site ran on our own computer. It had six pages, seven posts with pictures, three categories, seven tags and a menu. It also ran Yoast SEO, Redirection and Contact Form 7. The EmDash Exporter stopped at the connect step, so the content came across by export file. Every step below is one we did, unless it says otherwise. EmDash’s own Migrate from WordPress page has the full reference.

Coming from WordPress?

EmDash brings over your words, not your plugins. The table below says where each plugin’s job goes.

• Addresses change. EmDash’s Blog template, which we used, puts posts at /posts/your-post and pages at /pages/your-page. Every old address needs a redirect.
• There is no home-page setting. Until the site’s code changes, / lists your latest posts.
• Blocks that WordPress builds as the page loads, such as Latest Posts, arrive empty. Shortcodes, such as a contact form, arrive as plain text.
• Keep WordPress running until the move is checked. EmDash copies pictures from it.

What replaces each WordPress plugin

We make the plugins this list says to add. They are free, MIT-licensed and need no account.

• Yoast SEO, Rank Math. EmDash has titles, descriptions and canonical addresses in each page’s SEO box, plus a sitemap. For schema markup and a list of pages to fix, add SEO & Schema Markup (guide), from the Registry or npm.
• Redirection. EmDash has Redirects built in. To import your list, use SEO & Schema Markup (guide), from the Registry or npm.
• Contact Form 7, WPForms. EmDash’s official forms plugin (npm) keeps each enquiry under Submissions. To send each one to email, HubSpot or Zapier, add Lead Delivery (guide), from the Registry or npm.
• Site Kit, MonsterInsights, Complianz, CookieYes. Nothing is built in. Add Analytics & Cookies (guide), from npm only.
• Broken Link Checker. EmDash has a 404 Errors list under Redirects. Add Site Health & Broken Links (guide), from the Registry or npm.
• Popup Maker, OptinMonster, Hustle. Nothing is built in. Add Popups (guide), from npm only.
• The approval step of PublishPress. EmDash has roles: Contributor, Author, Editor. Add Content Approval (guide), from the Registry or npm.
• UpdraftPlus and other backup plugins. See EmDash’s Backups and recovery page.
• Anything else. Search Registry in your admin, or see How to find and install EmDash plugins.

What you need

• Your WordPress admin login.
• A backup of WordPress.
• A WordPress site that the internet can reach. EmDash will not fetch from localhost or a private network. The Exporter also needs https://.
• A new, empty EmDash site. When its setup screen asks “How do you want to start?”, choose Empty site.

Ask whoever looks after your site’s code to create the site and add these plugins. How to set up an EmDash site on Cloudflare for a business covers creating it. Leave out any plugin you don’t need. The forms plugin is EmDash’s own.

npm create emdash@latest
npm install @moorage/plugin-seo @moorage/plugin-site-health @moorage/plugin-analytics @moorage/plugin-lead-delivery @emdash-cms/plugin-forms

// astro.config.mjs
import seo from "@moorage/plugin-seo";
import siteHealth from "@moorage/plugin-site-health";
import { analyticsPlugin } from "@moorage/plugin-analytics";
import { formsPlugin } from "@emdash-cms/plugin-forms";
import leadDelivery from "@moorage/plugin-lead-delivery";

emdash({
  // keep your database and storage lines
  plugins: [seo, siteHealth, analyticsPlugin(), formsPlugin(), leadDelivery],
});

At Where will you deploy?, choose Cloudflare Workers, or Node.js to try the move on your computer. At Which template?, choose Blog. Then run npm run dev and open the address it shows.

Three of our plugins are also in the EmDash Registry. It needs Yes at Enable sandboxed plugins?, which only Cloudflare asks (why the Registry may be missing). Pick one route per plugin. A plugin moved later from code to the Registry starts with empty settings.

We used Yoast SEO 28.8, Redirection 5.10.1, Contact Form 7 6.2.4.1, EmDash Exporter 1.2.0 and the forms plugin 0.2.12. Our plugins were SEO & Schema Markup 0.1.11, Site Health & Broken Links 0.1.6, Analytics & Cookies 0.3.2 and Lead Delivery 0.4.2.

Two ways to move a WordPress site to EmDash

• Posts, pages, categories, tags, authors, pictures and drafts: both bring them across.
• Yoast or Rank Math titles and descriptions: the EmDash Exporter, if you switch it on. The export file does not.
• Menus, site title, logo and favicon: the EmDash Exporter 1.2.0 or later. The export file does not.

The EmDash Exporter is the official WordPress plugin from the EmDash team. The export file (WXR) is the .xml file from WordPress Tools, Export. What we say about the export file is what we saw. What we say about the Exporter comes from the plugin’s own list and EmDash’s docs.

Use the Exporter if you can install plugins on your WordPress site and it runs on https://. Otherwise use the file.

Use the EmDash Exporter plugin

Menus, the logo and the favicon need exporter 1.2.0 or later (EmDash’s Exporter steps).

1. Download emdash-exporter.zip from the latest release on GitHub.
2. In WordPress, go to Plugins, Add Plugin, then Upload Plugin.
3. Choose the zip and click Install Now, then Activate Plugin. You should now see Tools, EmDash Migration, headed “Migrate to EmDash in 3 simple steps”. Its list of what will be migrated includes menus and “Yoast SEO metadata”.
4. Click Generate migration key. A key starting em1. appears. If it says “Application Passwords are not available on this site”, read the site check above it. WordPress turns them off without https, and some security plugins do too. Fix that, or use the export file.
5. Click Copy key. Keep it private: it can read all your content.
6. In EmDash, click Import in the sidebar. You should see “Import from WordPress”.
7. Paste the key into Paste your migration key and click Connect.

Our test stopped here (see “What broke in our move”). The EmDash docs say the next screen has switches for menus, site identity and SEO values.

Import a WordPress export file

1. If you use Contact Form 7, go to Plugins in WordPress and click Deactivate under it. Otherwise every category and tag arrives twice (see “What broke in our move”). Activate it again after step 3.
2. In WordPress, go to Tools, then Export.
3. Choose All content and click Download Export File.
4. In EmDash, click Import. Under Upload directly, click Browse Files and choose the file. You should see “Content to Import” with one row per kind of content, for example “post, 7 items → posts, Ready”.
5. Untick any row you don’t want. If you skipped step 1, you will also see wpcf7_contact_form. Those are Contact Form 7’s forms, not content, so untick it.
6. Click Create Schema & Import.
7. On Map Authors, pick an EmDash user for each WordPress author. Leave a writer as Leave unassigned and EmDash credits them by name without a login.
8. Click Continue Import.
9. On Import Media Files, click Import Media. EmDash downloads each picture from WordPress. Ours failed (see “What broke in our move”).

You should now see your posts and pages under Content. Published ones are live on the new site, even where the editor says “Draft” (see “What broke in our move”). Drafts stay drafts.

What comes across, and what doesn’t

The file brought across posts, pages, drafts, dates, categories, tags and authors as bylines. Featured images still loaded from WordPress, because our picture copy failed. WordPress’s Sample Page came too: delete it if you never used it.

These did not come across:

• Yoast titles and descriptions. Each post’s SEO Title and Meta Description boxes were empty. The Exporter carries them; with the file, copy the important ones by hand. To see which pages need one, open SEO. Its To fix table lists, ten at a time, pages with no description and no excerpt: “No search description”.
• The menu. The site kept the template’s menu: Home, About, Posts. About went to /pages/about, which didn’t exist. Open Menus and click Edit. Delete About, then use Add Content for each page.
• Your home page. The address / shows your latest posts, and your home page moves to /pages/home. Google usually knows / best. EmDash has no home-page setting: the code file src/pages/index.astro decides what / shows. Ask whoever looks after your site’s code to make it show your Home page. Then redirect /pages/home to /.
• The Latest Posts block. It arrived as an empty HTML block. Delete it.
• The contact form. The shortcode appeared on the page as text: [contact-form-7 id="cf9f0a4" title="Contact form 1"].

Keep old links and Google results working: redirects

This step uses SEO & Schema Markup, from the EmDash registry or npm.

A redirect is a note that sends visitors from an old address to a new one. Lists go in the plugin: open SEO, then its Redirects tab. EmDash’s own Redirects, under Manage in the sidebar, is a different screen, used only for the post rule below.

Your old redirects. In WordPress, open Redirection’s Export tab, tick Include in export on Redirects, choose CSV in Format and click View. Copy the list and change each target to the new address: /our-menu/ became /pages/our-menu. In the Redirects tab, click Import from WordPress, paste into Your list and click Check list. Click Add 4 redirects (with your own count), then Add. You should see “4 redirects added from your list”. How to import your WordPress redirects into EmDash explains skipped rows.

Your pages. Yoast lists every page address at /page-sitemap.xml on your WordPress site, and posts at /post-sitemap.xml. Or open Pages, All Pages and set Screen Options to 100 items. Click Import another list and paste a plain list, one page per line:

/about-us/,/pages/about-us
/our-menu/,/pages/our-menu
/contact/,/pages/contact
/feed/,/rss.xml

The last line sends your old feed to the Blog template’s. We did not try it. Once / shows your home page, add /pages/home,/ too.

Your posts. Our WordPress used dated addresses, like /2026/03/our-first-sourdough/. One rule covers them all:

1. Click Redirects in the sidebar, under Manage.
2. Click New Redirect.
3. Type /[year]/[month]/[slug] in Source path.
4. Type /posts/[slug] in Destination path.
5. Click Create.

For plain Post name addresses, like /our-first-sourdough/, add each post to the plain list instead. We did not try this line:

/our-first-sourdough/,/posts/our-first-sourdough

Links inside your posts keep old addresses; the redirects catch them too. Category and tag addresses, like /category/recipes/, already worked.

Addresses you can’t redirect. EmDash’s redirects skip addresses ending in a file type, such as .xml or .jpg. From version 0.1.12 the plugin skips such a line when you import it, with the reason “Addresses ending in a file type, like .xml or .jpg, are not redirected by EmDash”.

• Yoast’s sitemap, /sitemap_index.xml. EmDash’s is /sitemap.xml, and its robots.txt names it. Tell Google after the switch (see the checklist below).
• Pictures under /wp-content/uploads/. Once your domain moves, those addresses lead nowhere, even with WordPress still running. So run Import Media until it finishes without errors before you switch. The EmDash docs say it then updates the picture addresses inside your content. Other websites’ links to old picture files will break.

Replace your contact form

1. Open Forms and click New Form.
2. Type a Name for the form, then use Add Field for each field. In each field, Label is what visitors see. Name is a short code word, such as email.
3. Set the Type to email for the email address and textarea for the message.
4. Click Create Form.
5. Open the Contact page. Delete the shortcode block with its ⋮ menu and Delete block.
6. Type /form, choose Form, pick your form and click Insert. The block shows the form’s ID, not its name.
7. Click Publish now, then Publish now again to confirm.

Contact Form 7 emailed you each enquiry. This form keeps them under Forms, Submissions. To get them by email, in HubSpot or in Zapier, add Lead Delivery from the EmDash registry or npm. How to send EmDash contact form enquiries to email, HubSpot or Zapier has the steps.

Add tracking and the cookie banner again

Tracking codes don’t move with your content. Add Analytics & Cookies, then open Analytics & Cookies, click Tools and paste the ID of each tool you use. The banner appears once a tool sets cookies. How to add Google Analytics and a cookie banner to an EmDash site has every step.

Check for broken links after the move

Site Health & Broken Links lists links that lead nowhere. Get it from the EmDash registry. Once your new site has a public address, read the Problems tab in Site Health. It also lists pictures still loading from WordPress. How to find and fix broken links on an EmDash site explains each fix.

Before you switch your domain

We did not switch a real domain.

1. Work through EmDash’s Verify before cutover list.
2. Open /. It should show your home page, not a list of posts.
3. Open five old addresses from Google’s results for your site. Each should land on the right page.
4. Send a test enquiry. Check it reaches your inbox (with Lead Delivery) or Forms, Submissions.
5. Read the Problems tab in Site Health, and fix the pages SEO lists.
6. Move the domain, as in step 5 of the business set-up guide.
7. In Google Search Console, submit sitemap.xml and remove sitemap_index.xml.
8. Keep the WordPress backup until the new site has run well for a while.

What broke in our move

• EmDash refused our local WordPress. It ran on our computer, without https. The key button said “Application Passwords are not available on this site”. Once WordPress gave a key, EmDash said “URLs targeting internal hosts are not allowed”. The Exporter’s check suggests “Run EmDash locally on the same machine”. We did; EmDash still refused. The picture copy failed the same way.
• Every category and tag appeared twice with the export file, once as “Events” and once as “events”. Contact Form 7 saves a language on its forms, and EmDash read that as a translation. It also listed the forms as a content type, wpcf7_contact_form. With Contact Form 7 deactivated, a new export into a fresh, empty site gave one of each. Don’t delete the copies by hand: when we deleted one, EmDash removed the real category from its posts.
• Live pages said “Draft”. The editor showed “Draft version” on imported pages, and the Menus picker said “Draft”. Visitors saw them all the same. To clear the label, open the page and click Publish now, then Publish now again. It then says “Live version”.

What it does not do

• Nothing copies your plugins’ settings, your theme or your users’ passwords.
• Forms, popups and page-builder layouts must be rebuilt.

If something goes wrong

• “URLs targeting internal hosts are not allowed.” EmDash can’t reach your WordPress. Use its public https:// address, or the export file.
• “Import Completed with Errors” with media errors. Check that each picture opens in a private window. Then run the import again: the EmDash docs say entries already there are skipped.
• Bot protection blocks the Exporter. The EmDash docs give a Cloudflare rule to let it through.

New guides and plugin releases appear in our RSS feed.

Changes to this guide. 2 November 2026: first version, tested on a test WordPress site.