jekyll-keepachangelog

A Jekyll plugin that parses a Keep a Changelog–formatted CHANGELOG.md and exposes it as structured data at site.data.changelog for use in Liquid templates.

Installation

Add to your site's Gemfile:

gem "jekyll-keepachangelog"

Then add to _config.yml:

plugins:
  - jekyll-keepachangelog

Run bundle install.

Configuration

By default the plugin reads CHANGELOG.md from your Jekyll site root. To use a different file:

changelog:
  file: docs/CHANGELOG.md

Data structure

site.data.changelog is an array of hashes, one per version section, in the order they appear in the file:

[
  {
    "version"    => "1.2.0",
    "date"       => "2024-03-15",   # String or nil for Unreleased
    "unreleased" => false,          # true only for [Unreleased]
    "sections"   => {
      "Added"  => ["Feature A", "Feature B"],
      "Fixed"  => ["Bug fix C"]
    }
  },
  {
    "version"    => "Unreleased",
    "date"       => nil,
    "unreleased" => true,
    "sections"   => {
      "Added" => ["Something upcoming"]
    }
  }
]

• version — the version string inside […], e.g. "1.2.0" or "Unreleased"
• date — the ISO 8601 date string after the - separator, or nil
• unreleased — true when the version label is Unreleased (case-insensitive)
• sections — hash of section name → array of item strings; only sections present in the file are included; an empty section is represented as []

Only top-level list items (lines starting with - or * at column 0) are captured. Indented sub-bullets are ignored.

Liquid template example

{% for version in site.data.changelog %}
  <h2>
    {{ version.version }}
    {% if version.date %} — {{ version.date }}{% endif %}
  </h2>

  {% for section in version.sections %}
    <h3>{{ section[0] }}</h3>
    <ul>
      {% for item in section[1] %}
        <li>{{ item }}</li>
      {% endfor %}
    </ul>
  {% endfor %}
{% endfor %}

CHANGELOG.md format

The plugin expects Keep a Changelog format:

# Changelog

## [Unreleased]
### Added
- Something coming soon

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

## [1.1.0] - 2024-01-10
### Changed
- Changed X

Development

bundle install
bundle exec ruby -Ilib test/changelog_test.rb

The parser (lib/jekyll-keepachangelog/parser.rb) has no Jekyll dependency and can be tested in isolation. The generator (lib/jekyll/changelog_generator.rb) wires the parser into the Jekyll build.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.txt.