In part 2 of this article, I go over the process I used to migrate my blog from WordPress.com to a static Jekyll site hosted on Amazon S3. Check out part 1 to learn more about the benefits and pitfalls that come with it. This guide assumes that you have (or want to develop) a working knowledge of *nix environments, and have (or want to develop) Google-fu skills needed to solve problems on your own. You will almost certainly run into problems – that’s life.

Install Jekyll

Installing Jekyll on OSX or one of the *nix variants is a breeze, just follow the instructions at Jekyllrb.com. Jekyll is not officially supported on Windows, but installation is possible.

Create your site

Once Jekyll is installed, you will need to create a folder that will hold all your files. This can be easily done by typing jekyll new _sitename_ at the command line. Alternatively, you can download a theme and start with that.

Select a Theme

Jekyll comes with a default theme, but you might want to use a different one. There are a variety of themes available at jekyllthemes.org, JekyllThemes.io, and other places. In my case, I copied the theme folder to my home directory instead of using jekyll new. Then I tried jekyll serve to test it out. At first it didn’t work and I found that I had to remove a default value for baseurl in _config.yaml, setting it to null. If you already have a site folder with a theme and post content and you want to change your theme, it’s probably best to create a new site folder and copy your content over rather than try to update the theme in place.

Migrate your content

Now that you have your site folder in place and have selected a theme, you will need to populate your _posts folder with your content. Before I migrated, I had only a handful of posts, so I was able to migrate them manually without much trouble. I just copied the text from my posts at Wordpress.com and pasted each post into a separate file in my _posts folder. Then I edited each post to add YAML front matter and markdown formatting. If you have a lot of posts, it may be worth the effort to seek out an automated solution. Like this. Use jekyll build to build your static site and jekyll serve to test it on your local machine. Building is where I ran into the most problems until I read that Jekyll processes files above your _site folder, and I had some junk in there that Jekyll didn’t know how to process.

Tweak CSS

You’ve installed Jekyll, set up a theme, and added your content. Use jekyll serve to see how it all looks on your local machine. Now is a good time to tweak the style to suit your tastes. I found that the theme I selected used some fonts that looked oddly grainy. I paid a visit to Google Fonts to select some new fonts. I added the embed code to my theme’s HTML templates. Then I hunted through the CSS in my theme and replaced the font-family values with those provided by Google Fonts. I also made some changes to font weight values because the defaults didn’t provide enough contrast between regular and bold text.

Configure Amazon S3

This can be tedious, but AWS provides excellent S3 Setup Instructions Amazon Simple Storage Service (S3) lets you configure storage buckets that can be made accessible via a web browser. This means that you can upload a set of static files and anyone with an internet connection will be able to view them. As I write this, AWS offers a 12-month trial period for new accounts. After the trial period ends, you will pay for storage volume and throughput. In my experience, I pay less than a dollar per month. Your cost could be higher if you have a lot of data to store (e.g. images, audio, video, Photoshop files), or you have a lot of site traffic. AWS provides tools that help you predict and control costs. I disabled logging for my site so that I wouldn’t have to deal with growing hosting costs as a result of expanding log data. Unless you want or need to process your own log files, I suggest setting up something like Google Analytics.

Configure DNS with Route53

Associate a domain name with your website. Technically, you don’t need to do this to have a static site hosted on S3, but having a custom domain will make it easier for others to find your site. You can register a domain using Route 53, or another registrar like Namecheap. After I set up Route 53 for my S3 buckets, I added the nameservers provided by AWS to my custom DNS configuration at my registrar. In the past, I’ve seen DNS updated within minutes, but this time I had to actually wait for 48 hours for the DNS caches to expire.

Set Up Google Analytics

I set up Google Analytics for my static site so that I would have some visibility into site traffic. There is a guide to using Google Analytics over at michealsoolee.com. The Google Analytics dashboard does not respond instantly to site traffic, so give it a day or two before expecting to see data in there.

Upload Your Content

The process for updating your site now looks like this:

  1. Update content on your local machine and test using jekyll build and jekyll serve.
  2. When you’re happy with how it looks on your local machine, open up your AWS dashboard, go to S3, and upload the contents of your _site folder to the root of your root domain bucket.
  3. Load the production site to make sure it’s working.

Now that everything has been set up, you should be able to access your site using the hostname associated with your S3 bucket through Route 53. You may have to wait a couple days for DNS caches to expire before this works.

That’s it! To reduce the amount of data being transferred each time you upload your site, leave out images or other large files if there have been no changes. Keep large files in their own folder so that they can easily be omitted from the upload. For further reading, check out How does Jekyll work? over at bytesandwich.