Wordpress to Contentful migration

Contentful is one of the most prominent headless CMSs at the moment. As such it provides you all the content management capabilities of traditional tools like WordPress while decoupling the delivery of this content via an API that can be used to retrieve content.

Headless CMS are quickly turning from the new kid on the block intro everyone’s favourite. And I totally understand why: it makes thinking about building a frontend so much easier, for once you actually know what is happening and we have great separation of concerns. For me as a webdev this is great stuff!

But it is also work, after all these old and dusty WordPress sites need to be migrated to those new an shiny, Contentful powered React based single page applications ✨ I have been building for clients. Luckily Contentful provides a range of tools to make this easier for. While the contentful-export and contentful-import can help you migrate Content Models and Entries from space to space the Content Management API helps you to manage your content. Thus today, let us take a look at how you can utilize it to migrate a blog from Wordpress to Contentful.

Let’s go on a journey.

You should understand this post as a guide and as basic examples. Code presented got my job done but will surely need adoption for your usecase.


Our end goal is to create blogposts, categories and assets in Contentful. For this we already have a content model set up. Many specifics of what follows will change according to the Content Model you are setting up.

Before we dive into the specifics of APIs lets make a plan on how to tackle this. The steps we are going to go through are:

  1. Get posts from Contentful
  2. Do some first processing on the posts
  3. Get categories from Wordpress
  4. Create a list of needed assets from Wordpress
  5. Create and publish assets in Contentful
  6. Create and publish categories in Contentful
  7. Create, link and publish blogposts.

1. Getting posts from Wordpress

To achieve this we will use the JSON based REST API Wordpress provides by default.

Using this we will first crawl all pages for posts, making requests to wp-json/wp/v2/posts?page=[pageNumber] until we get a 400 back.

I am handing a log function for logging here because I tied all pieces together using listr and wanted nicer integration for logs.

Once this function resolves we will have an array containing all blogposts from our Wordpress blog and are ready to do some first processing on them.

2. Prepare posts for usage

I generally like to prepare data for myself so that in later stages and during debugging I have a better overview. Wordpress gives us a lot of information that we don’t really need so lets get rid of that.

At the same time there is some information we would like that this API call has not given us. Mainly images that are present within the post. We could make more API requests to get this information. For this solution however we decided to extract image source urls and alt texts from the posts body using regular expressions.

In the above code we move information around and delete other as a simple clean up and to have nicer representation later on. Wrapping the body in a <div> tag is a curiosity of our system down the line where we use marked to generate the output on my final website where marked has trouble if there is no ingle top level element.

3. Get categories from Wordpress

After all we will be doing some more requests to the REST API. To make the following code easier I have a helper function called getJSON that given a URL will resolve with an object representing the JSON present at that URL.

As shown above we first reduce all our blog posts to a list of categories that we need. This way we will not get information about the same category multiple times.

Once we have unique categories we fetch all of them from the API and resolve with the gained information.

4. List all needed assets

We have two types of images that we might care about:

  1. featured images used as teasers and header images for blogposts
  2. images within the body of posts

As a result of this step we are looking for an array that looks a bit like:

link: ‘link to wordpress iage.jpg’,
description: ‘describe the image’, title: ‘and title it’, postId: ‘because linking back is nice’}, …]

To create Assets in Contentful we need to pass in a link to get the Asset from as well as a title and description for the Asset. We already created these types of objects for all images in the body of our posts when we first processed them. Which leaves us the first case of features images and to create one nicely flattened array.

Here you can see how I did this one a bit later on and renamed log to simpleLog with a default to console.log. Keep in mind that this is not meant to be perfect but working and inspiring code 😉

First we get the actual assets from Wordpress using their media numbers. After we get that we can also create objects representing featured assets and finally put them together with the body assets all the while doing some nice logging on the side.

Interlude: Contentful API

Good job 👍

We got halfway done. We have all the information we need to start creating assets and entries in Contentful. This is the perfect time to go and read up on the Management API. Or at least skim over Entry creation and Asset creation.

One thing you will notice for sure (since you went to those links and skimmed the code sample, didn’t you?) is how Contentful always includes locales in their requests. In fact fields first have locale attributes which then hold the actual content.

Apart from that the API, especially with the SDK, is straight forward to use. Just keep in mind that we need to publish Assets and Entries after creating them.

5. Create and publish assets in Contentful

Let me first give you a high level, pseudo code overview of what we will be doing here.

const createAndPublishAssets = () => {
space = await getTheRightSpace()
const createAndPublishSingleAsset = () => { let asset try { asset = await createAssetInContentful() } try { asset = await asset.publish() } createAndPublishSingleAsset( nextAsset ) } createAndPublishSingleAsset( firstAsset )}

That should give you a feeling for the general workflow.

Once you let this part run, go and grab a hot chocolate because for our ~400 assets this took over ten minutes to finish.

6. Creating and publishing categories in Contentful

After mastering the Assets this will be a walk in the park. This code follows the same pattern as explained in the pseudo code for assets but is short enough to present you the entire thing right here:

Really not much magic involved. The important thing is to keep a reference between your Entries and Assets in Contentful on the one hand and the original posts and images from Wordpress on the other. I decided to achieve this by adding wpCategory as an attribute of the Asset created in Contentful.

On to the final step!

7. Creating, linking and publishing blogposts

This is where it all comes together. Now that we have our images created as Assets in Contentful and our categories created as entries with the appropriate type our blogposts will tie all of this together.

Now keep in mind: we need to replace the links to our images with the one we got from the Assets we created in Contentful and we need to link the right category. Lets take a quick peek at linking entries through the Content Management SDK.

category: {
‘en-US’: {
sys: {
type: ‘Link’,
linkType: ‘Entry’,
id: categoryId

And with that piece of magic 🧙 in place, I present to you the creation of blogposts:

Make the pieces work together

Now we have all the pieces to make our migration work.

I decided to create one script per step and have them work in two ways:

  1. From the commandline creating files in between
  2. Programatically together with listr as a taskrunner

This way I could easily run single steps during development and have a single command with pretty output as the final result.

Photo credits:
Dog by Emerson Peters on Unsplash

Originally published at hoverbaum.net on March 22, 2018.

JavaScript enthusiast and developer for fun 👨‍💻