Tag-Based Filtering System for Jekyll Collection

Why Use Tags for Navigating Jekyll Collections

Unlike categories, which tend to be hierarchical and predefined, tags offer flexible, descriptive labeling. They allow users to discover content based on shared topics, features, or attributes. In knowledge bases, tutorials, or documentation, tags can act as a powerful way to group similar entries without enforcing rigid structure.

Jekyll doesn’t natively support tag pages for collections, but we can build this functionality manually using Liquid, includes, and front matter conventions.

Case Study: Multi-Tag Learning Resource Library

Imagine a collection called _resources containing educational materials. Each resource has tags in its front matter:

---
title: Understanding Liquid Filters
tags: [liquid,filters,basics]
summary: A beginner-friendly explanation of Liquid filters in Jekyll.
---

We want to create a tag-based interface that shows:

• All available tags (sorted)
• Each tag linking to a filtered view showing relevant resources

Step 1: Loop and List All Tags

We’ll extract all tags across the collection, remove duplicates, and sort them alphabetically:

{% raw %}
{% assign all_tags = site.resources | map: "tags" | join: "," | split: "," | uniq | sort_natural %}

  {% for tag in all_tags %}
    
{{ tag }}
  {% endfor %}

{% endraw %}

This gives us a basic tag index. We’ll create individual pages for each tag in the next step.

Step 2: Generate Dynamic Tag Pages

To avoid manually creating hundreds of tag pages, use a tag.html layout with a loop through all documents and filter by tag.

Create a layout at _layouts/tag.html:

{% raw %}
Resources tagged with "{{ page.tag }}"


  {% assign matched = site.resources | where_exp: "item", "item.tags contains page.tag" %}
  {% for item in matched %}
    
{{ item.title }}
  {% endfor %}

{% endraw %}

Then, generate tag pages using a generator plugin (if supported) or manually create them in bulk:

---
layout: tag
tag: filters
permalink: /tags/filters/
---

You can automate this in your build process if you’re hosting Jekyll locally. On GitHub Pages (which doesn’t support plugins), you must write them manually or use includes instead of dynamic pages.

Step 3: Use an Include Instead of Layout Pages (For GitHub Pages)

To make it GitHub Pages-friendly, use one page like /tags.html and generate all tag sections on the same page using an include.

Create _includes/tag-blocks.html:

{% raw %}
{% assign all_tags = site.resources | map: "tags" | join: "," | split: "," | uniq | sort_natural %}
{% for tag in all_tags %}
  
{{ tag }}
  

    {% assign tagged = site.resources | where_exp: "item", "item.tags contains tag" %}
    {% for entry in tagged %}
      
{{ entry.title }}
    {% endfor %}
  
{% endfor %}
{% endraw %}

Then render it from your tags.html page:

---
layout: default
title: Tags
permalink: /tags/
---

Browse by Tag
Explore all resources grouped by tag.

{% include tag-blocks.html %}

Step 4: Add Jump Navigation for UX

With many tags, it helps to add a jump list at the top:

{% raw %}

  {% for tag in all_tags %}
    
{{ tag }}
  {% endfor %}

{% endraw %}

Enhance with Tag Descriptions (Optional)

If you want richer tag sections, create a data file _data/tags.yml:

filters:
  description: Learn to manipulate output with Liquid filters.
liquid:
  description: Articles related to the Liquid templating language.

Then reference the description in your include:

{% raw %}
{{ tag }}
{% if site.data.tags[tag] %}
  
{{ site.data.tags[tag].description }}
{% endif %}

  {% for entry in site.resources %}
    {% if entry.tags contains tag %}
      
{{ entry.title }}
    {% endif %}
  {% endfor %}

{% endraw %}

Responsive Styling

Apply some responsive styling to make the interface user-friendly:

.tag-index {
  display: flex;
  flex-wrap: wrap;
  gap: 10px;
}

.tag-index a {
  background: #f0f0f0;
  padding: 5px 10px;
  border-radius: 4px;
  font-size: 0.95em;
  text-decoration: none;
}

ul.tag-list li {
  list-style: none;
  margin: 5px 0;
}

Use Case: Tags vs Categories

While categories are great for broader structure, tags give users more discoverability. You can combine both in your system:

• Categories for sidebar/global structure
• Tags for cross-topic exploration

Conclusion

With a tag-based navigation system, you empower users to explore content in a more natural and intuitive way. This improves time on site, internal linking, and SEO—all without relying on client-side JavaScript.

In the next article, we’ll explore how to combine tags and categories into a unified index interface to give users both structural and contextual pathways through your content.