building a tag archive system in jekyll for better navigation

Why Tags Matter in a Static Blog

Tags play a key role in helping users explore content on your site based on themes and topics. Unlike categories, which are broad, tags can offer granular navigation. In dynamic CMSs like WordPress, tag systems are built-in. In Jekyll, you need to build it manually — but with that comes flexibility and speed.

The Benefit of Tag Archives

Tag archives group posts under relevant keywords. Visitors can explore your blog by topics of interest, reducing bounce rates and increasing page views. It also helps with internal linking and crawlability by search engines.

Setting Up Tags in Jekyll Posts

Start by adding tags to your posts' front matter:

---
title: "Top SEO Mistakes to Avoid"
tags: [seo,optimization,beginner]
---

Enable Tag Display in Post Templates

Within your post.html layout, render the tags like this:

{% raw %}
<ul class="tags">
  {% for tag in page.tags %}
    <li><a href="/tag/{{ tag | slugify }}/">{{ tag }}</a></li>
  {% endfor %}
</ul>
{% endraw %}

Generating Tag Pages Automatically

To automate tag archive generation, use a custom plugin if building locally, or a data-driven approach for GitHub Pages. The plugin method is ideal if you're deploying outside of GitHub Pages.

Using a Plugin (Local or Netlify)

Create a plugin file in _plugins/tag_generator.rb:

module Jekyll
  class TagPage < Page
    def initialize(site, base, tag)
      @site = site
      @base = base
      @dir  = "tag/#{tag}"
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'tag.html')
      self.data['tag'] = tag
      self.data['title'] = "Posts tagged with '#{tag}'"
    end
  end

  class TagGenerator < Generator
    safe true

    def generate(site)
      tags = site.posts.docs.flat_map { |p| p.data['tags'] || [] }.uniq
      tags.each do |tag|
        site.pages << TagPage.new(site, site.source, tag)
      end
    end
  end
end

Or Use Collections and Manual Tag Pages (for GitHub Pages)

If you deploy on GitHub Pages and can’t use plugins, generate tag pages manually using a data file or loop. Start by creating a folder called tag, and inside it, create one HTML file per tag:

/tag/seo.html

Inside seo.html:

{% raw %}
---
layout: tag
tag: seo
title: "Posts tagged with SEO"
permalink: /tag/seo/
---

{% include tag-archive.html %}
{% endraw %}

Create a Tag Archive Include

Make a file _includes/tag-archive.html to list posts by tag:

{% raw %}
<h2>Articles tagged: {{ page.tag }}</h2>
<ul>
  {% for post in site.posts %}
    {% if post.tags contains page.tag %}
      <li><a href="{{ post.url }}">{{ post.title }}</a> - {{ post.date | date: "%B %d, %Y" }}</li>
    {% endif %}
  {% endfor %}
</ul>
{% endraw %}

Listing All Tags with Post Counts

You can also create a page that lists all tags alphabetically, with how many posts each has. Example for tag-index.html:

{% raw %}
---
layout: default
title: "Browse by Tag"
permalink: /tags/
---

<h2>Tags</h2>
<ul class="tag-index">
  {% assign tags = site.tags | sort %}
  {% for tag in tags %}
    <li>
      <a href="/tag/{{ tag[0] | slugify }}/">{{ tag[0] }}</a> ({{ tag[1].size }})
    </li>
  {% endfor %}
</ul>
{% endraw %}

Case Study: Tagging Boosted Time on Page

A travel blogger using Jekyll introduced a full tag archive system and noticed a 20% increase in average session duration. Visitors often explored related posts via tags, especially destination names or travel styles (e.g., "budget", "solo travel", "europe"). This led to better content discovery and improved SEO as Google found more internal link paths.

Design Tips for Tag Archives

• Style tag pages with consistent branding.
• Use readable permalinks like /tag/seo/.
• List posts by date, popularity, or even thumbnails.
• Add a brief intro or description at the top of each tag archive.

Conclusion

A tag archive system in Jekyll improves user experience, content discoverability, and SEO. Whether you're building with plugins or using manual methods for GitHub Pages, the investment pays off in engagement and structure. Tags not only help your audience explore — they help search engines understand your site's content architecture more clearly.