Migrate a Blog from Wordpress to Jekyll and Host it on Bitbucket

As an ocassional blogger, I hosted my blog with wordpress.com for years almost by default. It’s easy and dependable, but it’s not free if you want a custom domain, and well, it’s Wordpress. As a co-founder of Aerobatic, I’m supposed to have a cool Jekyll blog, or something, so here we are - How to move a Wordpress blog to Jekyll and host it on Aerobatic using the Aerobatic add-on for Bitbucket. Think Github Pages but with free private repos courtesy of Bitbucket, and CDN, custom domains, SSL, and more courtesy of Aerobatic.

Step 1: Export from Wordpress

First thing to do is to export your Wordpress blog by going to wordpress.com, and in the left nav of the admin console, click tools, and then export.

This will create an XML file of all your Wordpress data.

Step 2: Install exitwp

A Swede named Thomas Frössman created this nifty utility that converts the blog posts in the Wordpress XML file that you’ve just created, into markdown files that are needed for your Jekyll blog.

git clone https://github.com/thomasf/exitwp.git

In my case, I also needed to run an extra setup step:

sudo pip install --upgrade -r pip_requirements.txt

Once you’ve succcessfully installed exitwp, make sure you place your wordpress XML file into the wordpress-xml folder. Then, back in the root directory of the exitwp repo, from the command line type:

python exitwp.py

When it’s finished, there’s a new folder created called build in the exitwp repo root. Click through the various subfolders to the _posts folder and you should now see all of your old Wordpress blog posts in beautiful markdown, ready to drop into your shiny new Jekyll blog!

Step 3: Download a Jekyll Theme

Jekyll Themes is a great option for getting going quickly with a Jekyll blog. Once you’ve downloaded the theme of your choice, assuming you have Jekyll installed, in the root of your new Jekyll blog folder, from the command line, type:

jekyll serve

You should now have your blog running localhost. At this point, you can then copy over all of your markdown files into the _posts folder. Hit refresh in your browser and boom - you now have a Jekyll blog!

Step 4: Create a bitbucket repo

While the hardcore programmers will likely cackle in unison, personally, I’m a fan of SourceTree. So, using SourceTree, you can create a new private repo. Did I mention the private repos are free on Bitbucket?

Important: Make sure that in your gitignore file, you remove _site. This is where Jekyll generates your actual site, and since we'll be hosting this via Bitbucket, you'll actually want to commit those files to Bitbucket too.

Step 5: Install the Aerobatic Add-On

Now that you’ve created your repo on Bitbucket, you’ll next want to install the Aerobatic add-on. This is a one-time step and you won’t need to do this for each and every repo. So, from the Bitbucket UI, click on your avatar in the upper right corner, select manage account, and then in the left nav, you’ll see the add-ons sub menu.

Step 6: Publish your Site

From your repo summary page, click the Aerobatic Hosting link. Make sure that you select the sub-folder checkbox option and you tell Aerobatic where your code is, in this case, /_site

Once linked, you’ll get a dialog informing you that your app has been created and to push your code to publish your first version.

Once you’ve pushed your code, refresh the page and you should see that your first version is now live. One neat feature of Aerobatic is that it retains a full history of all previously deployed versions that are available via their own unique URL.

Step 7: Bonus - Custom Domains

In my case, my blog is now live at http://dundonian.aerobatic.io/, but if I wanted to add a custom domain, Aerobatic supports that too.

For example, jasongowans.net now points to my blog:

Note: Registering a CNAME can take some time to take effect (for mine it took about 10 minutes). In the meantime, you might get a "Bad Request" error if you type in the URL. Just be patient...

Step 8: Bonus - Form submission without PHP

With many of the Jekyll Themes, they come with a contact form that depends on PHP. Given that our hosting solution only support static content, that PHP won’t execute. So, what to do? Well, lately I’ve been using a service called formspree.

With formspree, you set your form to post to an email address of your choice, and formspree handles the rest.

In the JavaScript file that contains your contact form code, simply change the URL from referencing your contact PHP file to something like this:

$.ajax({ url: "//formspree.io/jason@aerobatic.com", type: "POST", data: { name: name, phone: phone, email: email, message: message },

The first time you submit the form, you’ll be asked to confirm the email address. This is a one time step that you’ll need to complete for both your localhost as well as your deployed public version.

Step 9: Bonus - Google Analytics

You’ve got your blog up and running and now you want to know how much traffic it’s getting. Setting up Google Analytics is pretty straightforward. In your _includes folder, create a new file called google_analytics.html

In that file, you’ll want to paste in the tracking code that Google provides. It should look something like the following:

Simply replace the “UA-999…” placeholder ID with your own Google Analytics tracking ID. Once this is done, you’ll then update the default.html page in your _layouts folder to include the google_analytics.html file you just created:

{{ "{% include head.html " }}%} {{ "{% include google_analytics.html " }}%} {{ "{% include nav.html " }}%} {{ "{{ content " }}}} {{ "{% include footer.html " }}%}

And that’s it! In less than an hour, we’ve converted our blog from Wordpress to Jekyll, and we’ve configured free hosting via Bitbucket that includes CDN, deployment versions, custom domains, contact form submission, and Google Analytics.

If you run into any issues following these steps, feel free to drop me a note via my contact form. You’re also free to check out my blog repo on Bitbucket so you can see things like the folder structure and my _config.yml etc. Good luck!

comments powered by Disqus