Change log parser for node.
npm install changelog-parser
[![npm][npm-image]][npm-url]
[![build][build-image]][build-url]
[![downloads][downloads-image]][npm-url]
Change log parser for node.
[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
```
npm install changelog-parser
This module exports a single function. It supports both callbacks and promises.
`js`
var parseChangelog = require('changelog-parser')
If provided with a callback, parseChangelog will invoke the function with the parsed changelog.
`js
parseChangelog('path/to/CHANGELOG.md', function (err, result) {
if (err) throw err
// changelog object
console.log(result)
})
`
If no callback is provided, parseChangelog will return a Promise.
`js`
parseChangelog('path/to/CHANGELOG.md')
.then(function (result) {
// changelog object
console.log(result)
})
.catch(function (err) {
// Whoops, something went wrong!
console.error(err)
})
You can optionally provide a configuration object parseChangelog function.
You must provide either filePath or text.
#### filePath
Path to changelog file.
`js`
parseChangelog({
filePath: 'path/to/CHANGELOG.md'
})
#### text
Text of changelog file (you can use this instead of filePath).
`js`
parseChangelog({
text: 'raw changelog text in string format'
})
#### removeMarkdown
Removes the markdown markup from the changelog entries by default. You can change its value to false to keep the markdown.
`js`
parseChangelog({
filePath: 'path/to/CHANGELOG.md',
removeMarkdown: false // default: true
})
There is also a command-line interface available if you install it with -g.
``
npm install -g changelog-parser
This installs a program called changelog-parser that you simply pass a CHANGELOG.md file.
``
changelog-parser path/to/CHANGELOG.md
This will print the JSON object representing the change log to the terminal.
Alternately you can run it without arguments and it will look for a CHANGELOG.md file in the working directory.
This module assumes your change log is a markdown file structured roughly like so:
`markdownchangelog title
A cool description (optional).
* Update API
* Fix bug #1
* make it so
[a.b.c]: http://altavista.com
`
Parsing the above example will return the following object:
`js`
{
title: 'changelog title',
description: 'A cool description (optional).',
versions: [
{ version: null,
title: 'unreleased',
date: null,
body: '* foo',
parsed: {
_: [
'foo'
]
}
},
{ version: 'x.y.z',
title: 'x.y.z - YYYY-MM-DD',
date: null,
body: '* bar',
parsed: {
_: [
'bar'
]
}
},
{ version: 'a.b.c',
title: '[a.b.c]',
date: null,
body: '### Changes\n\n Update API\n Fix bug #1',
parsed: {
_: [
'Update API',
'Fix bug #1'
],
Changes: [
'Update API',
'Fix bug #1'
]
}
},
{ version: '2.2.3-pre.1',
title: '2.2.3-pre.1 - 2013-02-14',
date: '2013-02-14',
body: '* Update API',
parsed: {
_: [
'Update API'
]
}
},
{ version: '2.0.0-x.7.z.92',
title: '2.0.0-x.7.z.92 - 2013-02-14',
date: '2013-02-14',
body: ' bark bark\n woof\n* arf',
parsed: {
_: [
'bark bark',
'woof',
'arf'
]
}
},
{ version: '1.3.0',
title: 'v1.3.0',
date: null,
body: '* make it so',
parsed: {
_: [
'make it so'
]
}
},
{ version: '1.2.3',
title: '1.2.3',
date: null,
body: '* init',
parsed: {
_: [
'init'
]
}
}
]
}
Expects versions to be semver compliant, otherwise sets version to null.
Each entry is available as an object in the versions array. The body of a given entry can be accessed using the following properties:
- body - A string containing all of the updates/changes/etc. for the current entry. This property includes both plain text and markdown.parsed
- - An object which points to one or more arrays of data for the current entry. All data for the current entry is present in the array at key _ (eg. parsed._). If the entry contains subheadings (eg. ### Added, ### Changed), then any items underneath each subheading will be present in an array at the corresponding key (eg. parsed.Added, parsed.Changed). Each array contains plain text.
CHANGELOG.md` standards are inspired by keepachangelog.com.
Contributions welcome! Please read the contributing guidelines first.
Log image is from emojipedia.