build a changelog section in jekyll using collections

Posted by -

Why You Should Add a Changelog to Your Knowledge Base

Transparency builds trust. Whether you're documenting a software project, a product, or an internal process, a changelog helps users track what has changed, when, and why. This is especially valuable for returning visitors who want to stay up-to-date without rereading everything.

Fortunately, with Jekyll collections, it’s easy to set up a structured, versioned changelog that integrates seamlessly with the rest of your site — all without a database or complex tools.

Step 1: Define a New Collection for Changelog Entries

Open your _config.yml and add the following to declare a new changelog collection:

collections:
  changelog:
    output: true
    permalink: /changelog/:path/

This creates a new type of content stored in the _changelog directory. The output: true line ensures each entry gets its own page.

Step 2: Create Sample Entries with YAML Front Matter

Inside a new folder named _changelog, create markdown files for each update. For example:

_changelog/2025-05-01-initial-release.md
---
title: "Initial Release"
version: 1.0
date: 2025-05-01
type: added
summary: "First release of the documentation platform"
---

We launched the initial version of the knowledge base, including the homepage, search functionality, and article templates.

Repeat this format for each change: updates, fixes, removals, improvements, etc.

Step 3: Create a Listing Page for All Changelog Items

Create a file changelog.md in your root directory with this front matter:

---
layout: default
title: "Changelog"
permalink: /changelog/
---

Then add Liquid code to loop through the changelog collection:

{% raw %}

Documentation Changelog



    
  {% assign sorted = site.changelog | sort: 'date' | reverse %}
  {% for entry in sorted %}
    
  • 
      
    {{ entry.title }} — {{ entry.version }} {{ entry.date | date: "%B %d, %Y" }}
    
      
    {{ entry.summary }}
    
      View details
    
    • 
  {% endfor %}


{% endraw %}

This displays the latest changes first, with summaries and links to full pages.

Step 4: Add Visual Tags for Change Types

To help users quickly scan updates, use badges for change types (added, fixed, changed, removed):

{% raw %}
{% assign badge_class = entry.type | append: "-tag" %}
{{ entry.type | capitalize }}
{% endraw %}

Style it in CSS:

.added-tag { background: #e6f7e6; color: #2e7d32; padding: 3px 8px; border-radius: 5px; }
.fixed-tag { background: #e3f2fd; color: #0277bd; }
.changed-tag { background: #fff8e1; color: #f9a825; }
.removed-tag { background: #ffebee; color: #c62828; }

Step 5: Enable Search Filtering by Version or Type

Include metadata like version or type in your JSON search index. This enables you to build filters later using JavaScript:


{
  "title": "Initial Release",
  "version": "1.0",
  "type": "added",
  "summary": "First release of the documentation platform",
  "date": "2025-05-01",
  "url": "/changelog/2025-05-01-initial-release/"
}

You can store this in a changelog.json file generated using Liquid or a Jekyll plugin like jekyll-feed or jekyll-json-feed.

Step 6: Link from Articles to Related Changelog Items

In each article’s front matter, you can optionally include a reference to a changelog update:

changelog_reference: 2025-05-01-initial-release

Then, in your article layout:

{% raw %}
{% assign update = site.changelog | where: "slug", page.changelog_reference | first %}
{% if update %}
  
This article was introduced in: 
    {{ update.title }}
  

{% endif %}
{% endraw %}

Step 7: Keep It Lightweight and Friendly for Beginners

You don’t need a database, backend, or CMS. Everything is just markdown, YAML, and Liquid. Easy to learn, fast to deploy, and readable by any text editor. It’s ideal for beginners hosting with GitHub Pages who want something powerful yet transparent.

Conclusion

By creating a changelog section with Jekyll collections, you give users visibility into your documentation lifecycle. It’s a small touch with a big impact—especially for frequent users or contributors. In the next part, we’ll explore how to handle versioned documentation in Jekyll using multiple collections and URL schemes.