custom category pages with jekyll

By -

Why Category Pages Matter

Category pages are essential for content-heavy blogs. They help users explore posts by topic, improve site navigation, and support internal linking structures that benefit SEO. Jekyll doesn’t provide built-in category templates, but it’s flexible enough to let us create them manually or dynamically.

Understanding Categories in Jekyll

In Jekyll, you can assign categories to posts using the front matter. Each post can have one or more categories:

---
title: "Optimizing Images in Jekyll"
categories: [jekyll,performance,media]
---

Jekyll automatically adds category information to each post’s metadata, but it doesn't create category-specific index pages by default.

Option 1: Manual Category Pages

The simplest method is to create a markdown or HTML file for each category manually. For example, for a category called jekyll, create jekyll.html at your site’s root:

---
layout: category
title: "Jekyll Posts"
category: jekyll
permalink: /categories/jekyll/
---

Create a Layout for Category Pages

Create a new layout file _layouts/category.html to filter posts based on category:

{% raw %}

Posts in Category: {{ page.category }}


    
  {% for post in site.posts %}
    {% if post.categories contains page.category %}
      
  • {{ post.title }}
    • 
    {% endif %}
  {% endfor %}


{% endraw %}

Option 2: Generate Category Pages Automatically

For blogs with many categories, generating category pages automatically is more efficient. Here’s how:

Step 1: Use a Plugin (If Allowed)

If you’re not using GitHub Pages or can run plugins, use jekyll-category-pages or build your own plugin to generate these pages dynamically.

Step 2: Or Use a Generator Script

Create a Ruby or shell script to scan all categories used in your posts and generate a static page for each category with appropriate front matter. Here’s a basic Ruby example:

require 'yaml'
categories = []

Dir.glob("_posts/*") do |file|
  data = YAML.load_file(file)
  categories.concat(data["categories"]) if data["categories"]
end

categories.uniq.each do |category|
  filename = "categories/#{category}.html"
  content = <<~HTML
  ---
  layout: category
  title: "#{category.capitalize} Posts"
  category: #{category}
  permalink: /categories/#{category}/
  ---
  HTML

  File.write(filename, content)
end

Step 3: Link to Category Pages

Once the category pages exist, you can link to them from your posts, sidebar, or footer. You can also list categories dynamically with:

{% raw %}

    
  {% assign cats = site.categories %}
  {% for cat in cats %}
    
  • {{ cat[0] }} ({{ cat[1].size }})
    • 
  {% endfor %}


{% endraw %}

Case Study: Small Blog with Niche Categories

A solo blogger with a library of 200+ posts used dynamic category pages to organize content by topic. Bounce rates dropped by 18%, and users viewed more pages per session. The clarity of site structure made a noticeable impact.

Best Practices for Jekyll Category Pages

  • Use consistent category naming (avoid both singular and plural)
  • Limit the number of categories per post to 1–3 max
  • Add introductory content or SEO text on each category page
  • Generate a sitemap that includes all category pages

Improving SEO with Category Pages

Category pages give you a great opportunity to rank for mid-tail and long-tail keywords. You can include a paragraph or two of keyword-rich content at the top of each category layout before the post list starts.

Conclusion

Creating custom category pages in Jekyll makes your blog easier to explore, supports topic clustering, and helps your SEO efforts. Whether done manually or automatically, they provide structure and context that readers—and search engines—love.