jekyll-keepachangelog

jekyll-keepachangelog reads a CHANGELOG.md file in Keep a Changelog format and makes the entire version history available as structured data at site.data.changelog. Build a proper version history page for your project site without manually writing HTML.

No existing Jekyll plugin does this. The few changelog-adjacent plugins either require a custom collection or manually maintained YAML — this one parses the markdown you already maintain.

Keep a Changelog Format

The plugin parses 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 becomes 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

Override the default file path if your changelog lives elsewhere:

changelog:
  file: CHANGELOG.md  # default

Source

Available on GitHub and RubyGems.

Live Demo

This site uses jekyll-keepachangelog to render its own version history. View the generated changelog →

gem install jekyll-keepachangelog