# keep-a-changelog

> Parse and generate changelogs following the [keepachangelog](https://keepachangelog.com/) format.

Latest version **3.2.0** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install keep-a-changelog
pnpm add keep-a-changelog
yarn add keep-a-changelog
bun add keep-a-changelog
```

Provides the command `changelog`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2026-09-07 |
| First published | 2017-12-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 115.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 69 |
| Author | Oscar Otero |
| Maintainers | oscarotero |
| Keywords | changelog, keepachangelog, parser |

## Links

- npm: https://www.npmjs.com/package/keep-a-changelog
- Repository: https://github.com/oscarotero/keep-a-changelog
- Homepage: https://github.com/oscarotero/keep-a-changelog#readme
- Issues: https://github.com/oscarotero/keep-a-changelog/issues
- npm.io page: https://npm.io/package/keep-a-changelog

## Dependencies (2)

- [ini](https://npm.io/package/ini.md) ^6.0.0
- [semver](https://npm.io/package/semver.md) ^7.7.4

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 3.2.0 (latest) — 2026-09-07
- 3.1.0 — 2026-08-03
- 3.0.6 — 2026-08-01
- 3.0.5 — 2026-06-03
- 3.0.4 — 2026-05-22
- 3.0.3 — 2026-05-13
- 3.0.2 — 2026-02-24
- 3.0.1 — 2026-02-23
- 3.0.0 — 2026-02-21
- 2.8.0 — 2026-01-08
- 2.7.1 — 2025-09-14
- 2.7.0 — 2025-09-07
- 2.6.2 — 2025-03-23
- 2.6.1 — 2025-02-24
- 2.6.0 — 2025-02-22
- … 38 more at https://npm.io/package/keep-a-changelog/versions

## README

# Changelog

Deno & Node package to parse and generate changelogs following the
[keepachangelog](https://keepachangelog.com/) format.

## Usage in Node

```js
import { parser } from "keep-a-changelog";
import fs from "fs";

//Parse a changelog file
const changelog = parser(fs.readFileSync("CHANGELOG.md", "UTF-8"));

//Generate the new changelog string
console.log(changelog.toString());
```

## Usage in Deno

```js
import { parser } from "https://cdn.jsdelivr.net/gh/oscarotero/keep-a-changelog@v3.1.0/mod.ts";

//Parse a changelog file
const changelog = parser(await Deno.readTextFile("CHANGELOG.md"));

//Generate the new changelog string
console.log(changelog.toString());
```

### Create a new changelog

```js
import { Changelog, Release } from "keep-a-changelog/mod.ts";

const changelog = new Changelog("My project")
  .addRelease(
    new Release("0.1.0", "2017-12-06")
      .added("New awesome feature")
      .added("New other awesome feature")
      .fixed("Bug #3")
      .removed("Drop support for X"),
  )
  .addRelease(
    new Release("0.2.0", "2017-12-09")
      .security("Fixed security vulnerability")
      .deprecated("Feature X is deprecated"),
  );

console.log(changelog.toString());
```

### Custom output format

By default, the output format of the markdown is "compact", that removes the
space after the headings. You can change it to follow the
[`markdownlint`](https://github.com/DavidAnson/markdownlint) rules:

```js
const changelog = new Changelog();
changelog.format = "markdownlint";
```

### Custom bullet style

By default, the bullet style of the markdown is "-". You can change it to use
other styles of bullet points:

```js
const changelog = new Changelog();
changelog.bulletStyle = "*";
```

### Custom tag names

By default, the tag names are `v` + version number. For example, the tag for the
version `2.4.9` is `v2.4.9`. To change this behavior, set a new
`tagNameBuilder`:

```js
const changelog = new Changelog();
changelog.tagNameBuilder = (release) => `version-${release.version}`;
```

### Custom compare links

By default, compare links are build compliant with GitHub format. To change this
behavior, set a new `compareLinkBuilder`:

```js
const changelog = new Changelog();
changelog.url = "https://bitbucket.org/oscarotero/keep-a-changelog";
changelog.compareLinkBuilder = (previous, release) =>
  `${this.url}/branches/compare/${release.version}%0D${previous.version}`;
```

### Custom Change Types

By default and according to the [keepachangelog](https://keepachangelog.com/)
format, the change types are `Added`, `Changed`, `Deprecated`, `Removed`,
`Fixed`, and `Security`.

In case you'd like add another type, you need to extend the `Release` class to
support new types. Additionally, you have to tell the `parser` that it should
create instances of your new extended `Release` in order to parse your changelog
correctly.

For example, we would like to add a type `Maintenance`. Extend the provided
`Release` class:

```js
class CustomRelease extends Release {
  constructor(version, date, description) {
    super(version, date, description);
    // add whatever types you want - in lowercase
    const newChangeTypes = [
      ["maintenance", []],
    ];

    this.changes = new Map([...this.changes, ...newChangeTypes]);
  }
  // for convenience, add a new method to add change of type 'maintanance'
  maintenance(change) {
    return this.addChange("maintenance", change);
  }
}
```

And once you want to use the parser:

```js
const releaseCreator = (ver, date, desc) => new CustomRelease(ver, date, desc);
const changelog = parser(changelogTextContent, { releaseCreator });
```

## Cli

This library provides the `changelog` command to normalize the changelog format.
It reads the CHANGELOG.md file and override it with the new format:

### Install the library as script

Deno:

```sh
deno install --global --allow-read --allow-write -fr --name changelog https://cdn.jsdelivr.net/gh/oscarotero/keep-a-changelog/bin.ts
```

Node:

```sh
npm install keep-a-changelog -g
```

Run the script:

```sh
changelog
```

To use other file name:

```sh
changelog --file=History.md
```

To generate an empty new CHANGELOG.md file:

```sh
changelog --init
```

To generate an empty new CHANGELOG.md starting from 1.0.0:

```sh
changelog --init --version=major
```

Create a new "Unreleased" version:

```sh
changelog --create none
```

Create a new "major", "minor" or "patch" version:

```sh
changelog --create minor
```

You can release automatically the latest "Unreleased" version:

```sh
changelog --release
```

If your "Unreleased" section has no version, you can specify it as an argument:

```sh
changelog --release 2.0.0
```

Or calculate it automatically:

```sh
changelog --release minor
```

Print the latest released version:

```sh
changelog --latest-release
> 2.0.0
```

Print the latest release:

```text
changelog --latest-release-full
## 2.6.1 - 2025-02-24
### Fixed
- NPM publishing [#55], [#56].
```

See available options:

```sh
changelog --help
```

---
_Source: https://npm.io/package/keep-a-changelog · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._