I’ve spent the better part of the last 5 days migrating this site from WordPress to Jekyll and Github Pages, and I’m pleasantly surprised by how smooth the whole process went (thanks in large part to a wealth of online documentation). I still have some updates and changes that I need to make to the site, but in the meantime, I wanted to share why I made the move, a few of the “gotchas” that I ran into, and the resources that were most helpful throughout the migration.

Why I moved

I’ve been blogging off and on since college. When I first started, I was hosting the site myself on a Linux server in my dorm room. Throughout the years, I moved through a variety of blogging platforms, and with every move, I’d either lose my content or have to export it in some proprietary format that effectively locked it into that platform. I hated the fact that my journal was strewn across all of these different places.

In the last few years, I’ve read about people that blog in Markdown, allowing them to write their posts as plain text files. This appealed to me because of the portability of the content. As long as I kept the files, I could feel pretty confident about being able to read them in 5, 10, 25 years. So I set out to move to a Markdown-based blogging platform.

After some research, I came across the Jekyll + Github Pages combo that had some additional benefits beyond supporting Markdown.

First, it is a very simple, lightweight blogging platform that can be managed locally on your computer. There’s no need to log into a website; you can use a text editor or VI and write a post or edit the site at any time with very little fuss and then push it to your GitHub repository. I was using Wordpress, and it added some friction since I had to work through their interface, which has a boatload of functionality that I never use and would never need.

Second, I have more control over the design and behavior of the blog than I did with WordPress. On the old site, I found myself constantly running into deadends while trying to tweak my site because I was using a PHP-based theme. I don’t know PHP well enough to navigate it comfortably, and I’m not interested in learning it. So more often than not, I’d get to a point in my tweaking that exceeded my ability and have to settle for good enough or abandon the idea altogether.

Third, with Github Pages, I could host my site for free, so I’d be able to get rid of a monthly bill for web hosting. I loved my host, asmallorange.com, and highly recommend them, but if I can save money, I’m going to save money.

Beware if you want to use HTTPS

As I mentioned, it only took ~5 days to get things up and running on Jekyll + Github. I was already familiar with HTML and CSS, so the majority of that time was spent getting a grasp on how Jekyll works, how it integrates with Github, and how I could tweak it to my heart’s content.

The only pitfall that I came across was realizing that Github Pages does not support HTTPS if you use a custom domain for your site. If you use the default website URL, USERNAME.github.io, then it will serve it securely by default. But if you are going to use a custom domain, then you need to set up a separate service to secure your site. It’s not ideal, but it’s good enough for now.

Helpful resources

There is a ton of documentation online about setting up a website on Jekyll + Github Pages. It can be overwhelming to find what you need, especially when you are first getting started with it. Here are the sites that I found most useful throughout the migration.






You can also view the source code for any sites hosted on Github Pages. This is a super helpful way to figure out how other people organized their sites or implemented something. Here’s my source code.