Designing Category-Based Navigation for Jekyll Collections

Why Category Navigation Matters for Jekyll Collections

For content-heavy Jekyll sites—especially knowledge bases, documentation sets, or niche blogs—clear navigation is crucial. One of the most effective approaches is to organize content into categories and present those categories in a structured, navigable layout.

While Jekyll doesn’t provide category navigation out of the box for collections, we can build a flexible system using Liquid logic and YAML front matter.

Case Study: Multi-Category Knowledge Base

Let’s assume we have a Jekyll collection named _kb representing a knowledge base. Each entry belongs to one or more categories defined in its front matter like this:

---
title: How to Use Front Matter
categories: [getting-started,configuration]
summary: Understand the basics of front matter in Jekyll pages.
---

We want to build a sidebar or sectioned layout that groups all entries by category, sorted alphabetically and linked automatically.

Step 1: Normalize and Extract Categories

In Jekyll, categories are simply a list of strings. To build category-based navigation, we need to:

1. Extract all unique categories from the collection
2. Sort them
3. Loop over each category and list associated entries

Create a layout or include where you render the navigation block:

{% raw %}
{% assign all_categories = site.kb | map: "categories" | uniq | join: ',' | split: ',' | sort_natural %}
{% for category in all_categories %}
  
{{ category | capitalize }}
  

    {% for entry in site.kb %}
      {% if entry.categories contains category %}
        
{{ entry.title }}
      {% endif %}
    {% endfor %}
  
{% endfor %}
{% endraw %}

This ensures that even if an entry has multiple categories, it will be included in each appropriate section.

Step 2: Creating a Category Navigation Page

Add a dedicated page that loads this logic. For example, create categories.html:

---
layout: default
title: Categories
permalink: /categories/
---


  {% include category-nav.html %}

Where _includes/category-nav.html contains the loop logic from earlier.

Step 3: Optional - Show Count Per Category

To show how many entries each category has:

{% raw %}
{% assign all_categories = site.kb | map: "categories" | join: ',' | split: ',' | uniq | sort_natural %}
{% for cat in all_categories %}
  {% assign count = 0 %}
  {% for entry in site.kb %}
    {% if entry.categories contains cat %}
      {% assign count = count | plus: 1 %}
    {% endif %}
  {% endfor %}
  
{{ cat | capitalize }} ({{ count }})
  

    {% for entry in site.kb %}
      {% if entry.categories contains cat %}
        
{{ entry.title }}
      {% endif %}
    {% endfor %}
  
{% endfor %}
{% endraw %}

This makes it easier for visitors to gauge which categories are most populated.

Step 4: Styling for Better UX

Here’s a minimal CSS suggestion to style your navigation panel:

.categories-index {
  max-width: 600px;
  margin: 0 auto;
}

.categories-index h3 {
  margin-top: 1.5em;
  font-size: 1.2em;
  color: #333;
}

.categories-index ul {
  padding-left: 1.2em;
}

.categories-index li {
  margin-bottom: 0.5em;
}

Using Includes for Reusability

If you want to show category-based navigation on multiple pages (like a sidebar or homepage), wrap the logic inside a reusable include:

{% include category-nav.html %}

This keeps your layout clean and improves maintainability.

Alternative Approach: Grouping by Front Matter Field

You can adapt the same pattern to group by other metadata fields such as tags, difficulty, status, or language. Just replace categories with the relevant field.

Grouping by Language Example

{% raw %}
{% assign langs = site.kb | map: "lang" | uniq | sort %}
{% for lang in langs %}
  
{{ lang | upcase }}
  

    {% for item in site.kb %}
      {% if item.lang == lang %}
        
{{ item.title }}
      {% endif %}
    {% endfor %}
  
{% endfor %}
{% endraw %}

This is useful if you’re building multilingual sites or topic-specific learning paths.

Bonus: Add Anchor Links for Each Category

If your list is long, add anchors so users can quickly navigate to a category:

  {% for cat in all_categories %}
    
{{ cat | capitalize }}
  {% endfor %}


{% for cat in all_categories %}
  
{{ cat | capitalize }}
  

    {% for entry in site.kb %}
      {% if entry.categories contains cat %}
        
{{ entry.title }}
      {% endif %}
    {% endfor %}
  
{% endfor %}

This improves the experience, especially on mobile or long pages.

Conclusion

Dynamic category-based navigation using Liquid opens up powerful content organization capabilities in Jekyll, all while staying within the limits of GitHub Pages’ static hosting. Whether for documentation, courses, or knowledge libraries, you can offer your visitors intuitive pathways to explore your content by topic.

Artikel selanjutnya akan membahas bagaimana membangun sistem tag-based navigation untuk Jekyll collections yang lebih fleksibel dan ideal untuk filter konten dinamis tanpa JavaScript tambahan.