How I migrated from Wordpress to Jekyll

Last weekend I migrated my personal blog from Wordpress to Jekyll. I tweeted as I went to keep some sort of record of what I'd done and the decisions I'd made. I also hoped that anyone else wanting to do the same thing would find it helpful.

It all started because GoDaddy reminded me that my hosting was about to expire. I'd been using Jekyll for the CS Workflow site and loved it.

That last part about hosting on Github isn't true. I hosted it on the CS Workflow server.

What is Jekyll and why use it?

Jekyll is a static site generator. A static site doesn't use any server side processing. Web browsers can easily handle static HTML, CSS, and Javascript. You've seen this in action if you have ever double-clicked a .html file on your desktop and had it opened in your browser.

Jekyll uses a template, processing rules, and content to generate a static site. Each page of the site has its .html file. The HTML file, along with the stylesheets, scripts, and images, can be uploaded to any web server. There are tons of ways to host static sites and almost all of them are free.

Wordpress, in comparison, uses PHP and MySQL to generate HTML each time a Wordpress page is viewed. The template is filled with content from the database, which is displayed by the browser. This only takes a few hundredths of a second.

Wordpress makes having a website really easy, especially is you use Wordpress.com and don't worry about your own hosting. Almost everything can be managed through the web-based admin console. You can be completely removed from everything technical, like HTML markup and installing plugins. Wordpress and platforms like it have allowed millions of people with no web development skills to have their own websites. That's a great thing!

Why bother with Jekyll then? Jekyll is faster. The site will be faster to use. Getting a new site setup is faster. Oh, and it supports Markdown by default. I love faster and I love Markdown, but the main reason I love Jekyll is that it puts me in total control over my entire site. I have instant access to style, layout, and content in a single text editor. I'm using Atom for my text editor at the moment, which I completely recommend.

It's totally a preference thing and there is a skills barrier to Jekyll, so it's not for everyone.

Exporting from Wordpress

Let's get on with it. The migration starts with exporting my content from Wordpress. I'd seen in Jekyll's documentation that there is support for migrating. I started there, but the documentation wasn't very thorough and I imagined using their method would waste time.

Off to google to find a good guide. I didn't want to spend a lot of time or energy on this migration, so a good tutorial saves both. I recommend the how-to guide on girliemac.com. This is what I followed. I'll assume your also using that as a reference and only chime in if I have something to add.

One of the first steps was to export comments to Disqus. I didn't have many comments, but I wanted to keep the few I had. I hadn't setup Disqus on a site before. It took than 3 minutes to complete the steps, going by the twitter timestamps.

Disqus had updated its export/import method and it was even easier that the way shown in the tutorial. Imports are queued and it took a few hours before mine were processed.

Jekyll's Wordpress exporter accessed the database remotely. The tutorial uses wordpress-to-jekyll-exporter, a Wordpress plugin. This plugin isn't searchable in the Wordpress plugin directory. I uploaded the plugin zip file to the plugin folder using FTP. Then I used the plugin installer in my Wordpress admin console to unzip, install, and activate the plugin.

The export was done with one click on the 'Export to Jekyll' link in the Wordpress console. This exported my posts and pages to Markdown. It also added any uploaded media to the export.

My only issue was that it used the .md Markdown extension instead of .markdown, which I prefer. I used the view/edit method in Filezilla and did a find and replace in the plugin file to change the .md to .markdown. I tried to use the plugin editor in the Wordpress console, but it went crazy when I tried to save the changes.

Setting up Jekyll

I didn't export my template. I decided to redesign instead. This is where I wasted the most time. I looked at theme sites for inspiration.

I can't remember what I searched for, but I found Poole, a Jekyll start kit built by Mark Otto of Bootstrap fame. Poole already looks pretty good, but has two themes. I used the Hyde theme, which I made a few changes to.

I think that's it. All I needed to do was to copy and paste the export Markdown files into the _posts directory and run jekyll build.

I needed to host the site myself because there are a few restrictions to hosting on Github. The main one that stopped me going with that option is not being able to use plugins. I use two plugins. The first is to figure out how old my daughter is. This is displayed in my bio in the left column. Jekyll uses Liquid templates, but doesn't come with a timeago filter as standard. The second plugin is jekyll-assets, which compiles the different stylesheets into a single, minified, gzipped, and cache-busting css file. This makes loading for the first time even faster.

To start, I created a new Github repository called chadfield-blog. This gives me cloud-hosted source control using git. Github also makes deploying changes really easy. To get the site on to the server I sshed in and ran git clone https://github.com/bchadfield/chadfield-blog.git from the directory I wanted to serve the site from. To get any future updates I run git pull.

By default Jekyll generates the site in the _site folder. For CS Workflow I'd set the build destination to a different directory which used its own git repository. This time I kept the source and generated site together.

The trade off of managing a single repository is that I'm deploying the source files to the web server and not just the static site. I point the web server to /chadfield-blog/_site instead of /chadfield-blog and have a few extra kilobytes on the server.

All I needed to do was add the site to the Nginx config, restart Nginx, and point the domain name at the server IP address.

server {
 listen 80;
 server_name www.chadfield.org;
 rewrite ^ http://chadfield.org$request_uri? permanent;
}

server {
 listen 80;
 server_name chadfield.org;
 root /home/deployer/chadfield-blog/_site;
 index index.html;
}

Publishing workflow

Obviously, the steps to get new content published is different to Wordpress. I'll lay out the steps needs and what I've done to make it easier.

  1. Write a new post.
  2. Create a new Markdown file in the _posts folder.
  3. Add meta-data and content to the Markdown file.
  4. Run jekyll serve and test locally that everything is okay.
  5. Commit changes to git using git add -A.
  6. Push local git repository to Github using git push origin master.
  7. ssh into the server and run git pull in the site directory.
  8. Check on my site that the changes are okay.

I automate steps 5, 6, and 7 using a rakefile. I use CS Workflow to write, get reviews, and export meta-data to Markdown.

desc "Commit changes to website repo"
task :commit do
	puts "Committing..."
  exec "git add -A && git commit -m 'Site update' && git push origin master"
end

desc "Update code in production"
	task :update do
  puts "Updating production..."
  exec "ssh user@server.com 'cd site-directory && git pull'"
end

To use that copy into rakefile.rb and change the ssh details and site directory. Then all I need to do is run rake commit and rake update.

Hopefully you found that helpful. There’s plenty of gaps, which is why I’ve called it titled it as how I migrated rather than a general how to. Really there’s not much to improve on the how to I referenced. Feel free to ask any questions or offer improvements I could make.

comments powered by Disqus