Moving to GitHub Pages Using Jekyll

Jekyll Mascot

When I started digging into GitHub, one of the first things I noticed was GitHub Pages. After getting GitHub setup on my computer (I was on Windows at the time so I setup GitHub’s Desktop Client) I made a repository for my personal page, bradonomics.github.io and pushed an HTML file as a test. That was exciting so I started digging for alternative ways to use GitHub pages. I had already been running Bradonomics via static HTML files for a few months as part of an SEO experiment, but when I wanted to make one change to my navigation menu, I needed to update 30+ pages …not fun.

Below are my notes on the process of getting to know Jekyll and getting it setup on GitHub.

“Installing” Jekyll Now

I quickly found the “blog aware static site generator” call Jekyll, but since I’ve never used Ruby I wasn’t sure how to get started. If you’re in this boat, check-out Barry Clark’s project called Jekyll Now. The basic idea is to fork an existing repository with a functioning Jekyll site, and then customize it to make it your own.

I hacked away at this for a couple days, and while it wasn’t quite what I was looking for, it did give me a great intro into the Jekyll system.

Starting Over with Skinny Bones

Most platforms have galleries showcasing theme designs and Jekyll is no different. I quickly found Michael Rose and his Skinny Bones theme. I hacked away at that for a few days trying to get it to conform to the basic design of my existing theme, but ultimately wasn’t getting where I wanted to go.

Scrapping it all to Merge Bradonomics with Medium

After spending enough time with other themes to understand the system, I decided to scrap the whole thing and start fresh. I knew the design I wanted was going to be unlikely to come from hacking at a pre-built theme.

I decided to keep a lot of what I liked in my old theme and apply some design concepts I’d seen around the web to give me more space. I was feeling a bit constrained before and wanted a full-width header. Since the Medium design had always been attractive to me, I added a full-width image as they have on some of their pages. This didn’t allow for the same navigation menu as I had before so using Chris Coyier’s “Off Canvas Menu” tutorial along with some help from Tab Atkins, Jr and Eric Meyer, I was able to add it to a hidden menu bar that slides in from the left.

You can click it …I’ll wait.

Installing Jekyll Locally to Avoid 30 Git Pushes Per Day

Somewhere along the line, I got tired of doing all those pushes when I was trying to get the CSS just right. Barry’s Jekyll Now project does a lot to get you running quickly, but it’s a pain during the development process to work on a live site. I decided to install Jekyll for Windows despite the “this might not work” warnings.

I have only one comment to make regarding the install: make sure you put the Ruby files in a directory without spaces. Since Windows installs by default to the “Program Files” directory, I put the Ruby files there. Turns out, Ruby doesn’t like the space in the directory name and wouldn’t load. Once the install path was changed, everything worked as advertised.

Learning a lot of HTML & CSS Along the Way

If you’re just starting out, working on a project like this will have you learning all kinds of things. I found Mark Otto’s Code Guide a big help, especially the CSS part.

I also found CSS Lint to be a great tool to find problems in my code.

Using GitHub For Hosting

After I had the Jekyll theme looking like I wanted, I thought it would be nice to use GitHub Pages as the new host for Bradonomics as the files were already there and a speed test said it was just as fast as my current web host.

I found this guide from GitHub, “Setting up a Custom Domain”, and this guide from David Ensinger, “Transferring DNS to CloudFlare for GitHub Pages,” to work perfectly.

CloudFlare with GitHub Pages
What my settings looked like when I was finished.

Update September 2015: Some time in early 2015, only a few months after publishing this, I moved back to WordPress. I was unable to get categories to work with Jekyll. It seems Jekyll doesn’t support something as basic as this, though there are some tutorials on the web where people have hacked a workaround. I’ve spent two days trying these tutorials and combing the code of sites that have categories, but still can’t get it to work. As much as I like the idea of Jekyll, I’m not smart enough to pull it off. So until someone writes a better tutorial or Jekyll starts supporting categories natively, I’ll stick with WordPress.

Update December 2015: I finally got categories working and bradonomics.com is back on Jekyll and hosted with GitHub.