Migrating from WordPress to Jekyll

Since its introduction in 2003, WordPress has become the most dominant CMS. According to W3Techs, WordPress is used by 26.8% of the top 10 million websites as determined by Alexa—essentially one-quarter of the entire web runs WordPress. For comparison, the next largest CMS would be Joomla at 2.8%.

Suffice it to say, there’s a reasonable chance that, if you are migrating to a static site engine, you are migrating from WordPress. This explains why many static site generators offer a WordPress importer (in fact, many only offer a WordPress importer). Let’s look at how you might use the importer provided by Jekyll.

Jekyll provides a very comprehensive list of available importers (24 by my count) from a wide array of CMS and other data formats. All of these run off of Jekyll Import Ruby gem. If you’ve already installed Jekyll, you already have Ruby Gems installed on your machine, so you can easily install the Jekyll Import gem via the terminal or command prompt.

gem install jekyll-import

Each importer also has their own set of additional dependencies. For instance, the WordPress importer also requires the gems for unidecode, sequel, mysql2, and htmlentities. At this point, you should have Ruby Gems installed, so you should be able to install all of these with one simple command-line statement.

gem install unidecode sequel mysql2 htmlentities

Once everything is installed, you can run the importer, providing the configuration via the command line. The easiest way to do this (in my opinion) is to first copy the configuration from the documentation into a text editor and edit it there before pasting it into the terminal or command prompt.

Here is the documentation’s configuration.

ruby -rubygems -e 'require "jekyll-import";
    JekyllImport::Importers::WordPress.run({
      "dbname"   => "",
      "user"     => "",
      "password" => "",
      "host"     => "localhost",
      "socket"   => "",
      "table_prefix"   => "wp_",
      "site_prefix"    => "",
      "clean_entities" => true,
      "comments"       => true,
      "categories"     => true,
      "tags"           => true,
      "more_excerpt"   => true,
      "more_anchor"    => true,
      "extension"      => "html",
      "status"         => ["publish"]
    })'

It’s important to note that each of the configuration settings above includes the default value. Thus, if the default value is sufficient for you (for example "host" => "localhost"), then you can feel free to remove it.

For example purposes, I’ll set up a WordPress variation of my static site samples example site (Figure 8-1), which is an Adventure Time! fan page. For this example, I don’t implement a full copy of the design in WordPress, I’m simply focusing on adding the blog posts.

Figure 8-1. A simple WordPress example site

After creating a new Jekyll site, I open the terminal or command prompt within the Jekyll site folder and run the importer with the configuration as follows:

ruby -rubygems -e 'require "jekyll-import";
    JekyllImport::Importers::WordPress.run({
      "dbname"   => "adventuretime",
      "user"     => "root",
      "password" => "root",
      "socket" => "/Applications/MAMP/tmp/mysql/mysql.sock",
      "host"     => "localhost",
      "categories"     => true,
      "tags"           => true,
      "extension"      => "html",
      "status"         => ["publish"]
    })'

The only thing “out of the ordinary” here is the socket setting, which, as I explained is the sidebar earlier, is necessary in order to connect to the MySQL database running on MAMP (Figure 8-2).

Figure 8-2. Running the WordPress importer

As you can see from the image, all eight posts from my sample site are imported as .html posts into the _posts folder of my Jekyll site (Figure 8-3).

Figure 8-3. A default Jekyll site with the imported WordPress posts

It’s important to note that the imported posts are HTML (regardless of the extension setting). They also include a ton of metadata added to the Jekyll front matter that is pulled from the WordPress site, including author details and even the WordPress ID. All of these values can be useful when trying to re-create the site as static.

Other Migration Options

Jekyll has the most exhaustive list of import tools, but other static site engines also offer some.

Hugo

Hugo offers importers from CMS such as WordPress and Drupal, blog hosting services such as Blogger and Tumblr, and even other static site generators like Jekyll and Octopress (a Jekyll-based tool).

Let’s take a really quick look at how to use the WordPress migration tools for Hugo. The nice part about this tool is that it is actually built as a plugin for WordPress, which makes the installation relatively simple.

First, download the code from the GitHub repository by clicking the “Clone or Download” button and choosing Download Zip. Unzip the file and place the unzipped folder in your WordPress /wp-content/plugins directory. If you go to your site’s admin, you should now see the plugin listed under plugins. Go ahead and activate it (Figure 8-4).

Figure 8-4. The WordPress to Hugo exporter plugin activated

Once activated, you should have an “Export to Hugo” option under your Tools menu. Selecting that will download a zip file containing the posts, pages, and files you’ll need to copy into Hugo.

Assuming that you have a new Hugo site already set up, you can simply copy the contents of the export post folder into your Hugo site’s content folder. All your posts should be there, converted nicely into Markdown.

Another nice feature of the plugin is that it also includes the images and uploads from your WordPress site’s wp-content/uploads folder. You can place this inside the static folder under your Hugo site to access any images and uploads from your new content.

This allowed me to easily add the thumbnail metadata for the Robust Hugo theme to the front matter for my posts as:

thumbnail: "wp-content/uploads/2016/09/wakeup.jpg"

And added back in my header images for my sample Adventure Time! site (Figure 8-5).

Figure 8-5. My sample site after importing it into Hugo displayed using the Robust theme

Building a Complete Hugo Site

For more detailed instructions on working with Hugo, please refer back to Chapter 4 which explains how to build a complete documentation site using Hugo.

gem install wp2middleman

wp2mm adventuretime.wordpress.2016-10-11.xml

Go Forth and Be Static

We hope that this book has given you a solid understanding of the static site generator ecosystem and the tools and skills necessary to build your first static site (or move your existing dynamic site to static). Perhaps you’d heard a lot about static site generators but were concerned that you’d give up too much by going that route. But the simplest solution to a problem is generally the best solution. So, if your site fits well with a static solution, why not get the added benefits of speed, security, and flexibility that they offer?

One thing that should be clear is that this ecosystem is growing and changing very quickly. New static site generators are created, existing ones are updated, and new third-party tools get introduced at a rapid pace. While this can seem intimidating, it represents a fast-growing community for a solution that is gaining more acceptance and usage every day.

As this book has shown, there are already a lot of mature and trustworthy solutions in the ecosystem, and getting started with them really isn’t that difficult. So there’s no need to hesitate—dive right in and go static!