# changelog-parser
Change log parser for node.
[![npm][npm-image]][npm-url]
[![build][build-image]][build-url]
[![downloads][downloads-image]][npm-url]
[npm-image]: https://img.shields.io/npm/v/changelog-parser.svg
[npm-url]: https://www.npmjs.com/package/changelog-parser
[build-image]: https://github.com/ungoldman/changelog-parser/actions/workflows/tests.yml/badge.svg
[build-url]: https://github.com/ungoldman/changelog-parser/actions/workflows/tests.yml
[downloads-image]: https://img.shields.io/npm/dm/changelog-parser.svg
## Features
- Parses a `CHANGELOG.md` file (or raw text string) into a structured object: a title, an optional description, and an array of version entries.
- Extracts each version's number, date, body, and list items, grouped by `### subheading`.
- Promise-based, with a legacy Node-style callback also supported.
- Optionally strips markdown from parsed entries.
### Supported formats
These common changelog formats are officially supported:
- **[Keep a Changelog](https://keepachangelog.com/)**: `## [x.y.z] - YYYY-MM-DD` headings, `### Added` / `### Changed` / etc. sections
- **[Conventional Changelog](https://github.com/conventional-changelog/conventional-changelog)**: `## [x.y.z](compare) (date)` headings, with or without top-level title
- **[Release Please](https://github.com/googleapis/release-please)**: `## [x.y.z](compare) (date)` headings with `### ⚠ BREAKING CHANGES` section
- **[Standard Version](https://github.com/conventional-changelog/standard-version)**: headings set by release type (`#` major, `##` minor, `###` patch)
- **[auto-changelog](https://github.com/CookPete/auto-changelog)**: `#### [vx.y.z](compare)` headings with the date on a `> ...` blockquote line
Maintained with 100% test coverage, verified on Linux, macOS, and Windows across all supported Node.js versions.
## Install
```
npm install changelog-parser
```
## Usage
This module is [ESM-only](https://antfu.me/posts/move-on-to-esm-only). It exports a named `parseChangelog` function that parses a changelog and returns a `Promise`.
```js
import { parseChangelog } from 'changelog-parser'
// async / await
const changelog = await parseChangelog('path/to/CHANGELOG.md')
// or as a promise
parseChangelog('path/to/CHANGELOG.md')
.then((changelog) => console.log(changelog))
.catch((err) => console.error(err))
```
A default export of the same function is also available (`import parseChangelog from 'changelog-parser'`).
CommonJS consumers on Node.js >= 22.12 can still `require()` it, but the function is no longer the module itself:
```js
const { parseChangelog } = require('changelog-parser')
```
### Callback
A Node-style callback is also supported. It was the original interface (the package predates native promises) and is kept for backwards compatibility. New code should use the returned promise.
```js
parseChangelog('path/to/CHANGELOG.md', (err, result) => {
if (err) throw err
console.log(result)
})
```
### Options
The first argument can be a path string or an options object (`string | ChangelogOptions`). You must provide either `filePath` or `text`.
```ts
interface ChangelogOptions {
/** Path to a changelog file. */
filePath?: string
/** Raw changelog text (alternative to `filePath`). */
text?: string
/** Strip markdown from parsed entries. Defaults to `true`. */
removeMarkdown?: boolean
}
```
### Command-line interface
There is also a command-line interface available.
```shell
npx changelog-parser