build status coverage report Gem Version

Changelog parser and transformer

Ruby gem for parsing Changelogs based on the format described at

The parser can read either a Markdown file or a folder structure with YAML files.

The output can be Markdown, YAML files or JSON.


Add this line to your application's Gemfile:

gem 'keepachangelog'

And then execute:


Or install it yourself as:

gem install keepachangelog


Command line

When using the parser there are four important options to pay attention to:

  • from - The input format
  • to - The output format
  • in - The input file or folder
  • out - The output folder (only used when output format is yaml)

See keepachangelog help parse for more information.

Markdown input

To dump a Changelog to JSON run the following command:

keepachangelog --in --from md --to json

YAML input

You can also express your changelog in YAML files inside a folder structure where each version is its own folder containing each change in a YAML-file.

Here's an example of a folder structure:

├── 0.1.0
│   └── 1-first-merge-request.yaml
├── 0.2.0
│   └── 3-another-cool-mr.yaml
├── 0.3.0
│   ├── 8-fixing-some-stuff.yaml
│   └── 9-add-new-feature.yaml
└── unreleased
    └── 11-minor-patch.yaml

Each YAML-file should be in the following format:

title: The ability to perform Foo while Bar is active
merge_request: 11
issue: 42
author: "@chbr"
type: New
  • title: A single sentence that describes the change
  • merge_request: The ID of the MR or PR (optional)
  • issue: The ID of the issue (optional)
  • author: The author of the change (optional)
  • type: The type of change, for example New, Changed, Fixed, Removed or Security.

To turn this into a Markdown document, simply run keepachangelog --in ./changelog --from yaml --to md

You can add meta data to your changelog in the file meta.yaml, placed inside the changelog folder, like so:

title: My Change Log
intro: This is my change log and I am using a cool gem to generate it.

The following meta data is read:

  • title: The title at the top of the Change log
  • intro: A text shown directly below the title
  • url: A URL to the git repository, used to generate links for versions that follows the format <url>/compare/FROM..TO

From Ruby code

If you want to use the API from your own Ruby code:

require 'keepachangelog'
parser = Keepachangelog::MarkdownParser.load('')
puts parser.to_json


After checking out the repo, run bin/setup to install dependencies. Then, run grunt test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.