Jekyll + Plugins + Github + You

Github’s Pages is a great “it just works” resource.

Except for when it doesn’t work.

So, for some reason, tags aren’t fully-implemented in Jekyll. They kind of work, but there’s no tag archive page. I went over this in my post on getting tags to work in Jekyll. The problem with that, though, is that Github disables any plugins you’re using when it processes/creates your blog (that’s what the --safe tag does).

How, then, do you get your blog (with tags) to load up on Github?

(I’m operating under the assumption here that you already have a Jekyll-powered blog set up on Github Pages, such that when you push commits to Github, it regenerates your blog for you.)

I’m going to lay out how to do this, and then how to automate the whole process so you can do it in just a few keystrokes.

1. Split Your Blog in Two

The first step is to clone your repo into a duplicate local copy. In my case, I took my local copy ~/applications/charliepark.github.com and cloned it to ~/applications/charliepark.github.com.raw.

This leaves you with the “raw” directory and the original directory (both identical).

2. Remove Your Old Content

In Finder, go into your original directory (again, in my case: ~/applications/charliepark.github.com) and delete all of the content. You do not want to do this via the command line, as it’ll either be tedious (you’d need to remove each directory / file) or it’ll be too aggressive, and you’ll lose your .git directory. The point here: You don’t want to lose your .git directory, as that’s how your local copy will talk to your repo at Github.

You should now have the “raw” directory (again, a clone of what you have at Github) and the now-empty (apart from your .git directory) original repo.

3. Regenerate Your Blog, in the “raw” Directory

This is pretty straightforward. Just cd to the raw directory … in my case:

cd ~/applications/charlie.github.com.raw

… and run the jekyll command.

This will regenerate your blog, in the ~/applications/charlie.github.com.raw/_site directory. You’ve probably already done this step once or twice before. (Note: You don’t want to run jekyll --server, as the point here is just to generate the blog, not to fire up a server.)

4. Copy the _site Directory Over To Your Original Repo

This is simple.

cp -r ~/applications/charliepark.github.com.raw/_site/* ~/applications/charliepark.github.com

Once you’ve run that command, you’ll now have: 1. Your “raw” directory 2. A subdirectory within the “raw” directory (_site), with the generated HTML 3. Your original directory, whose contents should now mirror the _site subdirectory of the “raw” directory

5. Add .nojekyll

When you add a file titled .nojekyll to your repo, Github won’t process your files as Jekyll files. I don’t think this step is strictly necessary, as we’re just sending the straight-up HTML files. But it can’t hurt. In your original directory (~/applications/charliepark.github.com), run:

touch .nojekyll

6. Commit and Push Your Repo

Add the files to your original directory’s git repo:

git add .

Commit the new version of the repo:

git commit -am "Converts to flat HTML files."

(Note: Your commit flags (-am) might differ from mine.)

Push the code to Github:

git push

7. Your Site Should Be Live

You can now go to your site (http://yourusername.github.com) and see your site.

8. Automate The Whole Thing

Once you’ve checked that it works, and that everything’s okay, it’s a good idea to automate the whole thing.

I added a shortcut to my ~/.bash_profile file:

alias build_blog="cd ~/applications/charliepark.github.com.raw; jekyll;cp -r ~/applications/charliepark.github.com.raw/_site/* ~/applications/charliepark.github.com;cd ~/applications/charliepark.github.com;git add .;git commit -am 'Latest build.';git push"
alias bb="build_blog"

So, now, once I’ve written a new post, or edited a post, or just want to get the site refreshed for some other reason, all I have to do in my command line is type bb, and it’ll regenerate the site, copy it over, run the git commits, and push it live to Github. I can now finish my post and then push it live to the site in about a second.

And it has tags.

Corrections?

I’m always half-expecting that some aspect of one of my writeups is totally broken. If you try this and have any issues, let me know (@charliepark). Similarly, if you try it and it works, let me know.