Developer docs

Migrating from WordPress

Migrate from WordPress and import your content to Ghost with this guide

The Ghost Concierge team, at your service

Let us handle the WordPress migration for you! This migration is included when you make an annual payment on the Ghost(Pro) Creator, Team, or Business plans. Send an email to concierge@ghost.org to learn more and get started.

With our WordPress Export Plugin you can smoothly move your content from WordPress to Ghost. In this guide we’ll show you how to export your content from WordPress, import it into a Ghost site, and take care of important details along the way.

Keep in mind that a migration from WordPress will not include custom fields, metadata, shortcodes, custom post types & taxonomies, or binary files. Just posts, pages, text, and images.

Prerequisites

The Export to Ghost plugin exports posts, pages, tags, authors and images from WordPress sites. Once you’ve imported your content from WordPress to Ghost, you’ll benefit from a suite of native features for all of the functionality you’re used to, without the need for additional plugins or downloads. Plus, if you want to connect all of your existing tools, we have hundreds of integrations to support that too.

Installing the plugin

Log into your WordPress site and navigate to Plugins using the sidebar menu. Click Add New and use the search field in the top right corner to search for Ghost Export, or you can follow this direct link to the plugin. You’ll know it’s the right plugin if the author is Ghost Foundation. Click Install Now and then Activate.

add plugin

activate plugin

Preparing your content for export

Once the plugin is activated navigate to Tools and then Export to Ghost with the sidebar menu. You’ll be presented with a small preparation guide to make you aware of what will be exported, and how to prepare your WordPress content for Ghost.

Converting categories to tags

Tags will be exported from WordPress, but not categories. This can be remedied using the Taxonomy Converter plugin.

add plugin

The following steps will permanently change the content structure of your WordPress site. If you are unsure of making this change please use the standard WordPress Export tool under Tools > Export to create a full backup of all your content.

Navigate to Import in the sidebar menu and click Run Importer under the Taxonomy Converter import item. Use the checkboxes to select the categories you want to import into your Tags and therefore into your Ghost site. Then click Convert Categories to Tags.


Tags and categories are almost exactly the same in terms of functionality. Categories are meant to mark pieces of content exclusively, meaning a post cannot exist in two categories at a time, a concept which can be managed very well with Tags in Ghost.

Exporting your content from WordPress

Now that your posts, pages, tags, authors and images are ready to be exported navigate back to Export to Ghost within Tools in the sidebar menu. Click the Download Ghost File button. If all goes well you’ll have downloaded a zip file containing all your content.

add plugin

Troubleshooting

In some cases your WordPress installation won’t be able to handle how much content is being exported, either because there’s a lot of data or because the WordPress install hasn’t been given enough time to process the data. If you do encounter these problems click .json below the download button. This will produce a single file which will contain all your posts, pages and tags and will skip the image downloading step.

add plugin

Images normally take the longest to download in any site export, so if you’re struggling with the download you might have better luck downloading them directly from the server, or asking your site administrator.

When the images are downloaded, they need to be stored with the following directory structure:

.
├── content/
│   └── images/
│       └── wordpress/
│          ├── 2021/
│          │   └── 02/
│          │       └── feb-image.jpg
│          │       └── feb-image-1024x786.jpg
│          └── another-image.jpg

You can zip the images directory, and upload to Ghost.

URL paths for content images will also need to be updated as the directory structure is different. Open the JSON file in your code editor, and use find and replace to replace the old structure with the new, for example:

  • Find https://exmaple.com/wp-content/uploads/
  • Replace with: https://exmaple.com/content/images/wordpress/

If you want to remove the /wordpress/ part of the image URLs, you will also need to change the feature_image value of each post in the JSON file to remove this.

Importing your content to Ghost

After the download is complete you’ll be left with a zip file containing your data and images. The JSON data file can also be used in these steps. Images will need to be uploaded alongside a JSON data file in a zip file.

add plugin

Log into Ghost admin and navigate to Labs view. Click the Choose file button within the Import content option and select your exported zip file, then click Import. All your content will then be imported into your Ghost site 🎉

add plugin

Ghost may warn you if there are any pieces of duplicate or malformed data.

Large image sets

If you have hundreds of images, you may find uploading multiple smaller zip files works better. Aim for approximately 100mb of images per zip file, and upload these one by one until they’re all uploaded.

Changing domains

In some cases exported data still contains the original WordPress domain you were using. This is fine if the new Ghost site is using the same domain, but if not you may need to modify the JSON file before importing. Open the JSON file in your code editor, which can be found by unzipping the export file, and use find and replace to replace the old domain with your new domain. Save the changes and zip the export up again.

Authors who were migrated will most likely need to reset their passwords, which can be done when logging into Ghost.

Pro tip: Just set up your site and want to remove the placeholder content? Head on over to Staff and select the Ghost user. Use the cog icon in the top right corner to delete this user, which will in turn delete all the placeholder Ghost content 🧨


Summary

Congratulations on your migration to Ghost 🙌. All that’s left to do is check over your content to ensure the migration has worked as expected. We also have a guide on how to implement redirects to make your transition smoother.