auto changelog integration for jekyll docs

By -

Why Automated Changelogs Matter in Documentation

Keeping documentation up to date is a fundamental part of any software or technical project. However, users and contributors often miss important updates if there's no clear changelog or update history. A manual changelog can be tedious to maintain and easy to forget. This is where automated changelogs come into play. By integrating changelogs into your Jekyll-powered documentation site hosted on GitHub Pages, you provide your users with a transparent and always-fresh update trail.

In this guide, we’ll explore how to build a fully automated changelog system using GitHub Actions, data files, and Liquid in Jekyll. You’ll learn how to generate change records dynamically from Git commits or pull requests and present them in a user-friendly interface on your documentation site.

Core Concepts Behind the Automated Changelog

Versioning vs Changelogs

Versioning refers to the state of your software or documentation at a particular point in time, typically tagged in Git (e.g., v1.0.0). A changelog, on the other hand, lists what has changed between those versions—bug fixes, feature additions, structural overhauls, and documentation updates.

What Makes a Good Changelog?

  • Clearly grouped changes (Added, Changed, Removed, Fixed)
  • Links to related commits or pull requests
  • Sortable or filterable entries
  • Integration with your existing documentation

Using GitHub Actions for Automation

GitHub Actions provides a powerful automation environment right within your repository. We'll use it to watch for push or merge events and automatically update our changelog file with recent activity.

Project Structure for Changelog Integration

Directory Planning

Before jumping into automation, let’s prepare the structure. Here’s a recommended layout:

/
├── _data/
│   └── changelog.yml
├── _includes/
│   └── changelog-entry.html
├── _layouts/
│   └── changelog.html
├── changelog/
│   └── index.md
├── .github/
│   └── workflows/
│       └── changelog.yml

changelog.yml in _data

This file stores structured data entries for each change. Each entry might look like:

- date: "2025-05-28"
  version: "v2.1.0"
  changes:
    added:
      - "New search filters for collections"
    fixed:
      - "404 error in knowledge base layout"
    changed:
      - "Refactored sidebar navigation system"
  links:
    pr: "https://github.com/yourrepo/pull/123"
    commit: "https://github.com/yourrepo/commit/abc123"

Displaying Changelog Data

Create a changelog page that loops through site.data.changelog:

{% raw %}
{% for release in site.data.changelog %}
  <section class="release-block">
    <h3>{{ release.version }} - {{ release.date }}</h3>

    {% if release.changes.added %}
      <h4>Added</h4>
      <ul>
        {% for item in release.changes.added %}
          <li>{{ item }}</li>
        {% endfor %}
      </ul>
    {% endif %}

    {% if release.changes.fixed %}
      <h4>Fixed</h4>
      <ul>
        {% for item in release.changes.fixed %}
          <li>{{ item }}</li>
        {% endfor %}
      </ul>
    {% endif %}
    
    <p><a href="{{ release.links.pr }}">View PR</a></p>
  </section>
{% endfor %}
{% endraw %}

Creating the GitHub Action for Auto-Changelog

Workflow Trigger

Create a file at .github/workflows/changelog.yml with the following basic setup:

name: Update Changelog

on:
  push:
    branches:
      - main

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate Changelog Entry
        run: |
          git log -1 --pretty=format:"%h - %s (%an)" > latest.txt
          # You can customize this to output YAML and append to _data/changelog.yml

Using a Changelog Generator

You can use third-party GitHub Actions like:

  • avtodev/markdown-changelog-generator
  • heinrichreimer/github-changelog-generator-action

Or write your own Node/Python script to parse Git logs and append to the YAML file.

Handling Data File Merging Safely

Because GitHub Actions are writing directly to a YAML file in your repository, you need to handle potential conflicts carefully. A good approach is to:

  • Read the file into a variable
  • Parse and insert new entry at the top
  • Commit and push the updated file back to the repository

This can be done in a shell script or via a dedicated tool like Python's PyYAML or Node.js’s js-yaml.

Final Touches and UX

Changelog Page Styling

Make your changelog accessible and visually appealing:

  • Highlight versions with background color
  • Add icons for “added”, “fixed”, “removed”
  • Include links to GitHub diffs or PRs

Navigation Placement

Add your changelog page to the main navigation so users can easily find what’s changed in your documentation. This is especially helpful for frequent visitors and contributors.

RSS or Atom Feed for Changelog

Consider generating an RSS feed for changelog updates using Liquid and XML layouts. This helps advanced users subscribe to changes programmatically.

Conclusion and Next Steps

With a structured approach and automation, your documentation site becomes a reliable source of truth. Users can trust that they’re always seeing the latest changes. Automated changelogs reduce manual work, improve transparency, and strengthen your documentation workflow on GitHub Pages.

In the next article, we’ll explore how to integrate user feedback or comments into your documentation site using GitHub Discussions and Giscus, while keeping everything static and lightweight.