Jekyll Categories: Creating A Category List Page

Now that I’ve been using Jekyll categories on this site for a few months, I decided I needed a page to list all of the categories I have. Implementing this was a pretty simple task, but there are a couple of things I had to do that were not obvious.

The categories generator plugin I adapted from the Jekyll site does the following: it creates a subfolder in the _site output folder named categories, and it builds a page for each category that lists all posts in that category. What it does not do is create the page I need that lists all of the categories used on the site.

To create the categories list page, I supposed I could have done this by further modifying the plugin. However, since the new page is simply a list of links to each specific category page, this seems to be something best handled with Jekyll’s Liquid templating.

The first thing to do is create a categories folder in the main site’s dev folder. Then, create an index.md file and build the categories list:

---
layout: page
title: Categories
---

{% for category in site.categories %}
<p>
  <a href="/categories/{{ category | first }}">{{ category | first }}</a>
  &nbsp;&nbsp;<span class="badge rounded">{{ category[1].size }}</span>
</p>
{% endfor %}

The bit that messed me up at first was how to get the name of the category. You’ll see above that the way to do this, thanks to a post on Stack Overflow, is to use category[0], or “better,” category | first. I thought it was simply category, but that outputs the full category array element, which includes the content of every post in the category – not what I want! What I want is the category title, which is the first element in the category array. Now that I understand this and how to use Liquid filters a little better, this makes sense.

The other piece was to have a link to the new categories page on the site’s main menu. I handled that by adding the new page to the pages list in the _config.yml file:

pages_list:       
  Categories: '/categories'
  About: '/about'
  Feed: 'http://feeds.feedburner.com/YourOwnGravity'

And the menu is built using the pages_list collection in the default.html layout:

{% for page in site.pages_list %}
     
  <small><a href="{{ page[1] }}">{{ page[0] }}</a></small>
{% endfor %}

So now, at build time, the main /categories/index.html page is created from /categories/index.md, the categories plugin continues to generate individual category pages in the categories folder, and the menu has a link to the new page. It all works fine and was pretty simple, with the small caveats (or rather, things I learned) described.

Categories    Meta    Technology