
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

