jekyll-keepachangelog
jekyll-keepachangelog turns a Keep a Changelog file into structured site data.
Open Source Plugin ∙

jekyll-keepachangelog

A Jekyll plugin that reads your CHANGELOG.md and turns its versions, dates, and sections into site.data.changelog for any template to use.

jekyll-keepachangelog reads a CHANGELOG.md file in Keep a Changelog format and puts the whole version history in site.data.changelog as structured data. You can build a proper version history page for your project site without writing the HTML by hand.

I couldn’t find another Jekyll plugin that does this. The few that come close need a custom collection or a YAML file you keep up by hand. This one reads the Markdown you’re already keeping.

Keep a Changelog Format

The plugin reads the standard format:

## [1.2.0] - 2024-03-15
### Added
- New feature A
- New feature B
### Fixed
- Bug fix C

## [Unreleased]
### Changed
- Work in progress

Data Structure

Each version turns into a hash in site.data.changelog:

- version: "1.2.0"
  date: "2024-03-15"
  unreleased: false
  sections:
    Added: ["New feature A", "New feature B"]
    Fixed: ["Bug fix C"]

Installation

Add to your Gemfile:

gem "jekyll-keepachangelog"

Add to plugins: in _config.yml:

plugins:
  - jekyll-keepachangelog

Template Usage

{% for version in site.data.changelog %}
  <h2>
    {{ version.version }}
    {% if version.date %}<span>{{ version.date }}</span>{% endif %}
  </h2>
  {% for section in version.sections %}
    <h3>{{ section[0] }}</h3>
    <ul>
      {% for item in section[1] %}
        <li>{{ item }}</li>
      {% endfor %}
    </ul>
  {% endfor %}
{% endfor %}

Configuration

If your changelog lives somewhere else, change the file path:

changelog:
  file: CHANGELOG.md  # default

Source

Available on GitHub and RubyGems.

Live Demo

I use jekyll-keepachangelog to render this site’s own version history. View the generated changelog →

gem install jekyll-keepachangelog