How to export WordPress posts to Gatsby

If you’re switching from WordPress to Gatsby, you’d probably like to transfer your existing content.

The gatsby-source-wordpress plugin can pull in data from a live WordPress install when Gatsby builds your static site. That’s a good solution if you want to run WordPress as a headless CMS. But what if you’d like to export your content from WordPress to Gatsby once and get rid of WordPress entirely?

One convenient way to add pages to Gatsby is to write your content in Markdown and to let Gatsby transform your Markdown content into pages. We can do this using the gatsby-source-filesystem and gatsby-transformer-remark plugins. Could we somehow export our WordPress content to Markdown?

There is a tool that can convert your WordPress content to Markdown files: wp2md. But wp2md does not create “front matter”, a block of YAML at the top of each Markdown file that the gatsby-transformer-remark plugin needs to read metadata about the content, such as a post’s title, slug, and category.

If you have several hundred posts on your website, like I did, it would be tedious to manually add the front matter to each Markdown file. 

Fortunately, a better tool exists. There is a WordPress-to-Hugo exporter; it can convert your WordPress content to Markdown files that contain the front matter we need to create pages in Gatsby.

In the remainder of this article, I’ll walk you through using the WordPress-to-Hugo exporter to create Markdown files from which we’ll generate pages in Gatsby.

(Note: If your WordPress site does not have many posts and pages, you can probably transfer your content more quickly by using wp2md and manually adding the front matter to the Markdown files. If you have a lot of content, or if you’d like to automate the process as much as possible, read on!)

Running the exporter

We’ll start by running the WordPress-to-Hugo exporter. You can run it from the WordPress admin area or from the command line. The exporter’s instructions explain how to do this.

After you run the exporter, you’ll find a new folder under wp-content/uploads, which contains your WordPress posts and pages. In the “posts” subfolder, there is a list of posts. Mine looked like this:

The list of Markdown files outputted by the WordPress-to-Hugo exporter.
Notice that the filename format is YYYY-MM-DD-slug and that one file has a filename consisting of the date and an empty slug. I’ll discuss why this matters in a minute.

(The exporter also produces a Hugo configuration file, config.yaml, which we won’t need.)

Open one of the Markdown files under posts and you’ll see that it has the front matter we need. Whoo! No need to manually add front matter to each post. 😅

The “front matter” is the content between the triple dashes at the top of the file.

If you have Gatsby set up to transform Markdown files to pages, you can now drop these files into the appropriate source folder (for me, that’s src/posts) and just like that, your posts will appear in your Gatsby-powered site!

Fixing the slugs

Chances are that you’ll need to do a little more work, though.

When you’re moving from WordPress to Gatsby, you probably want to maintain your site’s URL structure. For example, if a post lived at https://example.com/vegan-chocolate-cake, you’d like it to stay there.

By default, the WordPress-to-Hugo exporter creates Markdown files with the filename format YYYY-MM-DD-slug, because that’s the format that Hugo expects. If you use the Gatsby blog starter or you followed the Gatsby tutorial on adding Markdown pages, you’ll have Gatsby set up to use the Markdown files’ filenames as slugs.

That means your post might now live at https://example.com/2018-07-15-vegan-chocolate-cake instead. This will break existing incoming links and confuse search engines.

Fortunately, there are two ways to get around this problem.

Option 1: use the “url” field as the slug

In gatsby-node.js, you can modify createPages() to set the path of your posts based on the URL in the Markdown files’ front matter, rather than on the filename, like so:

createPage({
  path: post.frontmatter.url,
  component: blogPost,
  context: {
    slug: post.frontmatter.url,
    previous,
    next
  }
});

If you do this, you’ll have to add a “url” field to the front matter when you create new Markdown files, too.

Option 2: remove dates from filenames

An alternative is to (continue to) use the filenames of Markdown files as slugs for posts, but to remove the dates from the filenames.

To rename the filenames, you can use a regular expression to match the date portion of the filename and then replace it with nothing. Here’s a regular expression that matches the date portion of the filenames:

[0-9]{4}\-[0-9]{2}\-[0-9]{2}\-

(I uploaded this regex to RegExr, where you can play around with it.)

To batch rename files using a regular expression, I used a neat tool called transnomino, which runs on macOS. If you use a different operating system, you’ll have to find a different rename tool that supports regex.

Once you rename the files, your posts will maintain their existing URLs. Whoo! 🎉

Handling draft posts

If you have any draft posts in WordPress, you might run into an error when running gatsby develop after you place the Markdown files in src/posts.

Any draft posts you export will have a nonsensical date that the gatsby-transformer-remark plugin can’t parse. Unless you have an extreme number of draft posts, the quickest way to resolve this problem is to manually update the front matter for your draft posts.

Next steps

That was the core of it!

From here, you might want to:

  • Move your images from your WordPress wp-uploads folder to your Gatsby src folder and then import them to your Gatsby posts.
  • Transfer not only your WordPress posts, but also your pages.
  • Read the WordPress category and/or tags from the front matter and display them on your Gatsby site.

For now, I hope this guide was clear. Please let me know if you run into obstacles. Happy developing!

Drip vs. ConvertKit: a comparison and review

How do you choose a tool?

I like tools that are simple. Having more features available to you isn’t better if you don’t use them and they only get in the way.

I also like tools that are built by people who care. When the people making the tool care, you can trust them to improve the tool over time.

So that’s how I evaluate tools. And that’s how I evaluated two popular email service providers: Drip and ConvertKit.

How do they stack up?

TL; DR:

  • Drip is geared towards e-commerce; ConvertKit markets to “creators”.
  • Drip is more powerful (e.g. it has A/B testing and better reporting).
  • ConvertKit is easier to use and has built-in landing pages.
  • The price difference is negligible.

What Drip is better at

Drip focuses on e-commerce. It is designed primarily for people who sell lots of products online. If that’s what you do, you’ll likely prefer Drip.

Drip’s reporting features are detailed and comprehensive. You can analyze your emails and your audience’s responses as much as you like. ConvertKit has reporting features too, but they’re not as detailed.

If you have a sizable email list, you can get to know your audience better and make more sales using A/B testing (a.k.a. split testing). This technique has you sending different emails to different parts of your audience. The software will then tell you which version of your emails resonated more with your audience, such as which version was opened more often, which version generated more sales, etc.

Drip has extensive A/B testing features. You can A/B test individual emails (“broadcasts”) or emails that are part of an automated sequence. ConvertKit, on the other hand, will only let you A/B test broadcast emails—not emails that are triggered and sent automatically. So if you plan to do substantial A/B testing, go with Drip.

What ConvertKit is better at

Like I said, I prefer simple tools.

ConvertKit was created for professional bloggers and now markets itself as being for “creators”. And you can tell, because ConvertKit is simple. It is easier to use than Drip.

I prefer the experience of editing emails in ConvertKit. ConvertKit’s editor has everything you need and the interface does a good job of minimizing the clicks you need to get around the app. In Drip, I often feel like I need five clicks to do anything.

What else do I like about ConvertKit?

If you run a blog, you might want to email your blog posts to your subscribers. A handy way to do that is using a feature known as RSS-to-email. Both ConvertKit and Drip let you automatically send posts that appear in an RSS feed to your subscribers, but ConvertKit makes it way easier to do this. In Drip, you have to chat with customer support just to enable this functionality.

ConvertKit also has more integrations than Drip, although both apps do fine in the integrations department. If you need your email service provider to connect with another tool, chances are you’ll be fine with either ConvertKit or Drip. Both apps also work with Zapier, so you can connect them with other tools indirectly.

Speaking of integrations, ConvertKit has built-in landing pages. If you’re selling a product online, you probably want to create a landing page for it. This is free and easy to do in ConvertKit. Drip integrates well with LeadPages—because Drip is now owned by LeadPages—but the landing page functionality is separate and expensive.

Finally, the people behind ConvertKit are awesome. Nathan Barry and his team care about their product and their customers.

What they’re equally good at

Email is such an integral part of building an audience online that you shouldn’t be shy about spending money on a good email service provider. Still, you don’t want to over-pay. Fortunately, Drip and ConvertKit cost about the same. The key difference is that you can use Drip for free as long as you have 100 subscribers or fewer. ConvertKit has a 14-day free trial, but after the trial you’ll have to pay, regardless of how many subscribers you have.

Both apps also come with good support. The support teams are friendly and responsive. Enough said.

What about setting up your email opt-in forms? This is easy to do in both ConvertKit and in Drip. They each have an official WordPress plugin, for example.

Summary

You can’t go wrong with either Drip or ConvertKit.

They are similar enough that you can easily try both of them for a while and simply pick the one that feels most intuitive to you.

If you’d rather choose now, then:

Choose ConvertKit if:

  • You value simplicity.
  • You like using software built by people who care.
  • You are an online creator.

Choose Drip if:

  • You want to use A/B testing.
  • You like to have detailed reports available to you.
  • You run an e-commerce business.

I hope this was useful. Good luck deciding and let me know if you need help.

Yours,

— Peter Akkies