Tags in Jekyll without using plugins
Jun 6, 2014 • Hamish Willee
This post shows how to support tags in jekyll without using plugins. This means you can have tags in blog sites that are built automatically using Github’s inbuilt Jekyll.
Introduction
Jekyll has rudimentary support for tags. You can add tags to pages and specify how, if present, they are to displayed in your layouts. You can also list all tags that have been applied to all posts across the site.
What isn’t so obvious is how to get (and link to) a list of all topics with a particular tag.
The common approach for supporting tags is to use a custom plugin to create a separate index page for each tag. Unfortunately this means that you can’t use automatic publishing of your sources when you create a new post, because Github’s version of Jekyll won’t run custom plugins. Instead you will have to manually rebuild your sources and push the new site to the publishing repository.
However there is no real necessity to have separate index files for each tag, which is why a plugin are needed. The alternative is to have a single index page with a separate heading, anchor and list of blog posts for each tag. Linking to the correct index from a tag is then as simple as opening the index page with the correct anchor.
This approach is easy to implement, and since it does not use plugins, Github will automatically publish the updated index whenever you add a new post.
Adding tags to a page
Tags are added to the tags variable in the page/post front-matter:
The tags can be accessed in pages and layouts using the Liquid variable page.tags
. You can also get a list of all the tags that have been applied to all posts using the site.tags
variable.
Tags index page
Create a tags page for the index: Tags.md. The page needs two elements:
- A list of all the tags on the site, for easy navigation
- A heading and anchor for each of the tags, containing the list of tagged articles.
The list of tags on the site can be obtained by iterating through the site.tags
variable using a Liquid for-loop. Note that each iteration returns an array, and the tag is the first item: tagitem[0]
.
To create the heading and anchor for each tag we again iterate the site.tags
. Under each heading we iterate through all the site posts, listing only those which contain the current tag.
Finally, when we list each post, we can iterate through its tags and list them with the title. For this page the URL we create is a local link within the page to an anchor for the tag - e.g. #jekyll.
Note that the code above also contains various HTML elements that are used for styling.
Updating layouts
The layouts need to be updated to automatically display tags if they are defined for the current page. This can be done in the posts.html layout near the heading. The tags are displayed by iterating the page.tags
variable. Note below that in this case we link to tags.html#current-anchor.
Adding tags to blog listings
Adding tags to blog listing is virtually the same as adding them in the tag index. Iterate through site.posts
using a for loop, then access the tags for each page using its tags
variable.
Next steps
One improvement might be to add JavaScript to the tags.md
which would hide all sections except the one for the current tag. I am in two minds on this - it is useful to see all tags present and having the others is not overly distracting.
Summary
The “single page tag index” approach is used on this site. I particularly like that I don’t need to move away from automatic Jekyll generation of the site in order to support tagging.