Tags for Jekyll on Github
Tags for Jekyll on Github
Jekyll is a great way to build a blog-capable website. It’s straightforward but powerful and, best of all, generates a completely static site which can be hosted practically anywhere. GitHub Pages has become a popular hosting solution for Jekyll sites. It’s free and leverages the power and availability of GitHub. Did I mention that it’s free?
There is, however, one downside to hosting a Jekyll site on GitHub: no plugins. GitHub disables Jekyll plugins for security reasons, which is understandable but unfortunate. Extending and customizing Jekyll is much easier when you can run arbitrary Ruby code during the site build.
One practical side effect of this is that it is difficult to properly implement tags for a Jekyll blog. This has been talked about all over the web, including on the Jekyll issue tracker. It looks doubtful that an official solution is coming, so let’s find a workaround!
Well, almost exactly that. No per-tag page is actually generated. Instead, I use a pop-up modal to display a list of posts when the user clicks on a tag name. In some ways, this is more dynamic and nicer than a separate page for the per-tag posts. However, you can’t link to a tag page using this solution.
With that caveat in mind, to the code!
A Static “API”
First, get Michael’s solution working as a separate page displaying all tags. We’ll still let the user access this page if they choose.
Next, let’s create another page that will generate the same information, rendered in JSON format. In my project, I put the HTML rendering in /tags.html and the new JSON rendering in /tags_json/index.html. As this data is JSON, the file shouldn’t have an .html extension, but that’s the extension Jekyll needs to process the file, so we’ll just have to work around that later. In this file, add the following:
Once you’ve added it, build the site with Jekyll and visit the /tags_json/ page in your browser. You should see a densly formatted JSON version of all the tags and their posts. I’ve opted for a dense format that is less readable than I’d like, but I wanted to minimize bandwidth in case the post/tag count gets high down the line.
Using the API
Now let’s make a simple AJAX request for the data from your website. Assuming you have JQuery integrated into your site, you could do this in a script after JQuery has been loaded:
Validate the request fired off and returned your tag data by using your browser’s developer tools. Note the “dataType: ‘json’” option, which forces JQuery to interpret the returned data as JSON. This is important, as the server sets a MIME type of “text/html” on the file. If you hit problems, the most likely cause of failure is incorrectly formatted json being rendered by Jekyll. Check the /tags_json/index.html file for any issues.
That code assumes you are using Twitter Bootstrap. You’ll need to change the modal template and modal display code if you are using another UI framework.
Once you get it integrated into your site, create an instance of the TagManager using the following:
Applying the TagManager is almost as simple. I render my tags using Liquid template code like this:
The “return false;” keeps the click from following the default link.
I’ve implemented this tag method on this blog. Click on a tag on any of the posts to see it in action.
And take a look at the code in the GitHub Repository for the site. The relevant files are:
- /tags.html – The HTML rendering of all tags on the site.
- /tags_json/index.html – The JSON rendering of the tag data (aka, the API).
- /_layouts/default.html – The default Jekyll layout, which defines the site skeleton and uses the TagManager.
- /_layouts/post.html – The post Jekyll layout, which shows rendering of tags in a post.
If you have any questions about this, please get in touch with me.