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
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:
… and run the
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 (
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:
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
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.
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.