Taking a sidestep from fizzbuzzing and playing with Giphy APIs, I thought I’d implement tag index pages properly on this blog (without any plugins). My Makers Academy related posts keep being muddied up with unrelated posts, and I needed a way to filter them out.

If you’re unfamiliar with Jekyll, it’s a static site generator. You can type up some basic .md files as blog posts and Jekyll generates the HTML for a fully functioning website. It has a templating engine built-in, which keeps the code DRY (don’t repeat yourself) by using templates that swap in variables and partials. It can even fill out templates with JSON/YAML data. I won’t go into detail about how to get started as it’s all in the documentation, although I did attempt to create a boilerplate of sorts that aims to take the difficulty out of Jekyll by letting Gulp.js automate a lot of stuff.

Whilst categories work fine, tags aren’t really ‘supported’ in Jekyll. The documentation tells you how to tag your posts, but then you’re left to scratch your head in confusion from that point onwards.

layout: post
title:  Using tags in Jekyll
date:   2016-05-19 10:00:00 +0100
categories: general
# Here we go, tags!
tags: [this is how, I do, it]
# The rest of blog post content goes down here

Here’s an example of the YAML Front Matter block for a blog post. The tags are this is how, I do and it, just as expected. It’s a pain but you’ll need to manually create a page for every tag you have. For my tag it (really useful name), I’d create an it.html page with this snippet:

# Loop through all the posts tagged 'it'
{% for post in site.tags.it %}
  # Print the title of each post
  title: {{ post.title }}
  # Loop through all the tags this post is tagged as
  # and print the name of each tag
  {% for tag in post.tags %}
    <br>tag: {{ tag }}
  {% endfor %}
{% endfor %}

Assuming I only have one sad post tagged it, the html generated would be:

title: Using tags in Jekyll
<br>tag: this is how
<br>tag: I do
<br>tag: it

That’s pretty much it! I’d then go ahead and fill out it.html with {{ post.content }} or link the title to the {{ post.url }}.

If you’re still confused, have a look at the repo for this blog. I always find that I need to be able to explore how something is structured before I really understand what’s going on.