My Jekyll Extensions
UPDATE: I have extracted my customizations into portable extensions using that you can use in your own Jekyll-powered blog. Read Jekyll Extensions -= Pain for more information on how to use jekyll_ext to extend Jekyll without modifying the Jekyll gem codebase. (Updated on 19/01/2010)
I’ve been getting some of traffic from my listing in the Jekyll Sites page, so I take it that people are interested in the extensions I made to get Jekyll to fit my needs. In this post I’ll explain some of the modifications that I did and how to use. I will also point out the modifications I made to the Jekyll code base, in case you wan’t to incorporate some specific changes in your own customization.
Category Listing
Jekyll by default only allows you to get a list of posts that belong to a category if you specify that category name: site.categories.CATEGORY. But what I also wanted to do was iterate through the all the categories I have in order to generate a category/topics page.
After stumbling around the Jekyll code base and messing with things, figuring out what code does what, I managed to do exactly what I wanted. You can see the results for yourself in the Topics section of this blog. The alteration was actually quite simple (after a bit of fiddling), you can find the code in lib/jekyll/site.rb under the following methods: site_payload and make_iterable.
To use this feature, all you need to do is iterate over site.iterable.categories. You then have access to the category’s name and the posts that belong to it by accessing the properties name and posts. Here’s part of the code I used to generate my Topics for a complete example: Category/Topics Listing Liquid Markup (Sorry for linking to a Gist, but I wasn’t able to properly display that code here due to my failed attempt at escaping the liquid markup I’m trying to show you).
Shorten Filter
I wanted my home page to display just the most recent post, and then below it display the titles of the other posts in chronological order (this is a blog after all). But, because some titles might be a bit long, I wanted a way to limit the number of words that can appear in a title and only show some words from the beginning and end with “…” for the middle. For example, my post title “Syntax Highlighting Code in Posts with Textmate” when passed to the shorten filter becomes “Syntax Highlighting Code…with Textmate”.
The code for this filter can be found under the method shorten in lib/jekyll/filters.rb. Just call it like any other filter and pass the maximum number of characters as its argument, like so: {{ post.title | shorten: 45 }}
Categories in _posts
I made this alteration because I wanted to use categories in my blog, but I didn’t want them spread around in various directories. Now all my posts live happily under their own category in the _posts directory. This feature was implemented easily in 4 lines of code, which can be found in lib/jekyll/post.rb under method initialize (lines 41-45).
Pretty URL but without the Category
At the time I setup my blog, I was so busy hacking away that I completely missed that you could specify the exact permalink structure in your “_config.yml” file. So my customization has an additional permalink style, which can be found under the method template in lib/jekyll/post.rb, called “pretty_no_category”. At least now what appears under the permalink option in “_config.yml” is permalink:pretty_no_category rather than permalink: /:year/:month/:day/:title.
Future Extensions
In the future, I plan on adding the same support for Category iteration to Tags. This should be implemented quite easily seeing as I already have a helper function (make_iterable mentioned in Category Listing) that I used for the categories. Other than that, Jekyll serves its purpose just fine!
I didn’t put the code for my site on GitHub because I didn’t think that people would be interested in it. But if you would like to check it out, drop a comment. If I see there’s enough interest, I’ll put it up.