{"id":16508513,"url":"https://github.com/osteele/changelog-parser","last_synced_at":"2026-05-09T21:51:10.476Z","repository":{"id":57134388,"uuid":"424533676","full_name":"osteele/changelog-parser","owner":"osteele","description":"An npm package that parses CHANGELOG files from markdown to JSON.","archived":false,"fork":false,"pushed_at":"2021-11-04T15:01:22.000Z","size":129,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-25T09:18:39.659Z","etag":null,"topics":["changelog","changelog-parser"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osteele.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-04T09:12:19.000Z","updated_at":"2024-12-14T15:36:49.000Z","dependencies_parsed_at":"2022-09-04T09:11:35.373Z","dependency_job_id":null,"html_url":"https://github.com/osteele/changelog-parser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fchangelog-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fchangelog-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fchangelog-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fchangelog-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osteele","download_url":"https://codeload.github.com/osteele/changelog-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241460013,"owners_count":19966511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["changelog","changelog-parser"],"created_at":"2024-10-11T15:45:56.872Z","updated_at":"2026-05-09T21:51:10.441Z","avatar_url":"https://github.com/osteele.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# changelog-parser\n\nParse ChangeLog files that are written in the Markdown format suggested by [keep\na changelog](https://keepachangelog.com), e.g.:\n\n```text\n# Release Notes\n\n## [1.0.0] - 11/04/21\n\n### New\n\n- Connect to turbo-encabulator on serial port\n\n### Fixed\n\n- Solar versus sideral time in launch time calculation\n- Inches versus millimeters in telescope mirror size\n```\n\n## Install\n\n```sh\nnpm install --save-dev @osteele/changelog-parser\n```\n\n```sh\nyarn add -D @osteele/changelog-parser\n```\n\n## Usage\n\n```js\nimport parseChangeLog from \"@osteele/changelog-parser\";\n\n// either:\nconst filePath = \"/path/to/changelog.md\"\nconst changelog = parseChangeLog({ filePath });\n\n// or:\nconst text = fs.readFileSync(filePath, 'utf-8');\nconst changelog = parseChangeLog({ text });\n\n// =\u003e changelog:\n{\n  title: \"Release Notes\",\n  versions: [\n    {\n      title: \"[1.0.0] - 11/04/21\",\n      version: \"1.0.0\",\n      date: \"2021-11-04\",\n      changes: [\n        {\"New\": \"Connect to turbo-encabulator on serial port\"},\n        {\"Fixed\": \"Solar versus sideral time in launch time calculation\"},\n        {\"Fixed\": \"Inches versus millimeters in telescope mirror size\"},\n      ],\n      categories: {\n        \"New\": [\"Connect to turbo-encabulator on serial port\"],\n        \"Fixed\": [\n          \"Solar versus sideral time in launch time calculation\",\n          \"Inches versus millimeters in telescope mirror size\"\n        ]\n      }\n    }\n  ]\n}\n```\n\nSee\n[`./example/changelog2html.ts`](https://github.com/osteele/changelog-parser/blob/main/example/changelog2html.ts)\nfor an example.\n\nSee the [source\nfile](https://github.com/osteele/changelog-parser/blob/main/src/index.ts#L6) or\nthe [TypeScript type declaration\nfile](https://unpkg.com/@osteele/changelog-parser@latest/dist/index.d.ts) for\nthe full types of the options, and the properties of the return value.\n\n### Options\n\nYou must provide either `filePath` or `text`. The remaining parameters are\noptional.\n\n#### text\n\nText of the change log.\n\n#### filePath\n\nPath to the change log. This is read synchronously and decoded as UTF-8.\n\n#### categorySortOrder\n\nIf non-null, re-order change categories within each version.\n\nSee the\n[source code](https://github.com/osteele/changelog-parser/blob/main/src/index.ts#L53)\nfor the default order.\n\nSpecify `null` to disable sorting.\n\n#### defaultTitle\n\nThe default title. This is used if the source text doesn't have a title (H1\nelement, via `# Title` markdown notation).\n\n_Default_: `\"Release Notes\"`\n\n#### recognizeColonSections\n\nIf true, recognize e.g. `Changed:` as equivalent to `### Changed`.\n\n_Default_: `true`\n\n#### omitUnreleasedVersions\n\nOmit versions whose titles are equal to \"Unreleased\", ignoring case.\n\n_Default_: `true`\n\n#### outputFormat\n\nThis controls the format of the `ChangeLog.changes[].body` and\n`ChangeLog.categories[key]` strings.\n\nValues:\n\n- `html`: An HTML string, e.g. `\"An item with \u003cem\u003eemphasis\u003c/em\u003e and a \u003ca\n  href=\"target\"\u003elink\u003c/a\u003e.\"`\n- `text`: Text content, e.g. `\"An item with emphasis and a link.\"`\n\n_Default_: `html`\n\n## Comparison with other packages\n\nThis package provides similar functionality to the\n[parse-changelogs](https://github.com/SamyPesse/parse-changelog) and\n[changelog-parser](https://www.npmjs.com/package/changelog-parser) packages,\nexcept that:\n\n1. This packages recognizes multi-line text in change lists. (The other packages\n   return only the first line.)\n2. This package can returns HTML strings, instead of plaintext or markdown.\n   (parse-changelogs returns only plaintext. changelog-parser can return either\n   plaintext or markdown.)\n3. Dates are in ISO format.\n4. There are options to sort changes by category, to omit unreleased versions,\n   and to recognize additional formats for change category sections.\n\n|                                         | @osteele/changelog-parser | changelog-parser | parse-changelogs |\n| --------------------------------------- | ------------------------- | ---------------- | ---------------- |\n| Can return immediate value              | ✔️                         |                  | ✔️                |\n| Can return `Promise`                    |                           | ✔️                |                  |\n| Can call async callback on completion   |                           | ✔️                |                  |\n| Can return HTML  change body text       | ✔️                         |                  |                  |\n| Can return Markdown  change body text   |                           | ✔️                |                  |\n| Can return unformatted change body text | ✔️                         | ✔️                | ✔️                |\n| Date format                             | ISO                       | same as input    | ISO              |\n| Reads multi-line list items             | ✔️                         | x                | x                |\n\n## History\n\nI wrote this package the [Visual Studio Code P5 Server\nExtension](https://github.com/osteele/vscode-p5server), because\n`parse-changelogs` removed link formatting and didn't recognize multi-line\nchanges and I didn't see an easy way to get from that code to what I wanted.\n\nI wasn't aware of `changelog-parser` until I went to publish this as an npm\npackage, so I haven't looked at how difficult it would be to modify it to meet\nmy requirements.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fchangelog-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosteele%2Fchangelog-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fchangelog-parser/lists"}