Tagging on GitHub Pages

I now have my blog on GitHub Pages but there are certain features that I would kind of like that I was unsure that I would be able to do with a static file and one of these was tagging or categories.

The Jekyll static site generator is blog aware and they weren't going to miss out on blog tags/categories feature.

Adding Categories to Your Blog Posts

The categories are defined by in the meta data that you place at the top of your files, just add them as a yaml list:

---
layout: default
title: Tagging on GitHub Pages
categories:
- blogging
- github
- tags
---

Create a Tags Page

We have our pages now with a list of categories and the next thing to do is to produce a list of tags and every page that has that tag. The way I approached this was to create a new page called tags.html:

---
layout: default
title: Tags
---
<ul>
{% for category in site.categories %}
  <li><a href="#{{ category | first }}">{{ category | first }}</a></li>
{% endfor %}
</ul>

<h2>Articles by tag</h2>

<ul>
{% for category in site.categories %}
  <li><a name="{{ category | first }}">{{ category | first }}</a>
    <ul>
    {% for posts in category offset: 1 %}
      {% for post in posts %}
        <li><a href="{{ post.url }}">{{ post.title }}</a></li>
      {% endfor %}
    {% endfor %}
    </ul>
  </li>
{% endfor %}
</ul>

At the moment it is not the prettiest thing but it does the job. This is built using the Liquid Templating language and there were a number of things to be aware of:

All of the categories in all of the pages are contained in the site.categories and each element is an array that contains all of the posts for that category but there is a problem... The first element of the array is actually the category name and the subsequent elements are the posts, therefore to get the name we can use {{ category | first }} which is a special filter that gets the first element.

So, there is a problem with the displaying of the pages if we have to ignore the first element, therefore we have to skip the first element using the offset filter {% for posts in category offset: 1 %} which skips the first element of the category array.

Creating a basic tag list

I also want to get the list of tags for the site into my side-bar along with the twitter feed, so people can jump to other interesting articles. The tag list will link right back to the tags page I made earlier to get the list of related posts.

The mechanism that I used to get the list was extremely similar to the way I generated the tags page but I make use of the {{ category | size }} filter to get the size of the array, but remember the first element is just the name, not a post, therefore there is an extra filter that I added on get the last element of the array which is the list of posts {{ category | last | size }}:

<html>
...
<div id="tags">
	<h3>Tags</h3>
	<ul>
	{% for category in site.categories %}
	  	<li><a href="/tags.html#{{category | first}}">
	    {{category | first}}</a> 
	    ({{category | last | size}})</li>
	{% endfor %}
</div>
...
<html>

Summary

This gives me now a starting point to start making a tag cloud for my blog, this is the simple implementation that I can think of but it didn't take me too long. I hope you find this useful if you are thinking of creating your own GitHub Pages blog.

Tags: blogging github tags

blog comments powered by Disqus