{"_id":"@bestikk/changelog","_rev":"3-a6090fc3b18617e7538968a7c9bcbd19","name":"@bestikk/changelog","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@bestikk/changelog","version":"1.0.0","keywords":["changelog","keepachangelog","asciidoc","downdoc","release","cli"],"author":{"name":"Guillaume Grossetie"},"license":"MIT","_id":"@bestikk/changelog@1.0.0","maintainers":[{"name":"ggrossetie","email":"ggrossetie@gmail.com"}],"homepage":"https://github.com/bestikk/bestikk-changelog#readme","bugs":{"url":"https://github.com/bestikk/bestikk-changelog/issues"},"bin":{"bestikk-changelog":"bin/cli.js"},"dist":{"shasum":"758de309523173da7c6108055acd657892933047","tarball":"https://registry.npmjs.org/@bestikk/changelog/-/changelog-1.0.0.tgz","fileCount":8,"integrity":"sha512-Wca915JLuauV5eFF1ToykM+mlgjDRpFTGmk/I4FjEvm8g0lQ/mcy2c51xv5+DaOZ/7aQeEghomrjGtUAxmK66w==","signatures":[{"sig":"MEUCIQCYEpsEZKgHu/ZXzYbLOURnPmXzap+ofkj52MGktkmHfwIgWNUkRg7VCzk/bNZLCEQCmFNAp66vWMNvffer4kceNyo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22602},"main":"index.js","type":"module","engines":{"node":">=18"},"gitHead":"6df4af36beb1312fb4ac890a76881685e775212c","scripts":{"lint":"biome check .","test":"node --test","format":"biome format --write .","lint:fix":"biome check --write ."},"_npmUser":{"name":"ggrossetie","email":"ggrossetie@gmail.com"},"repository":{"url":"git+https://github.com/bestikk/bestikk-changelog.git","type":"git"},"_npmVersion":"11.12.1","description":"Manage a Keep a Changelog changelog (AsciiDoc or Markdown): roll the Unreleased section into a dated release, and extract a release as Markdown release notes.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"@biomejs/biome":"2.5.7"},"optionalDependencies":{"downdoc":"^1.1.0-stable"},"_npmOperationalInternal":{"tmp":"tmp/changelog_1.0.0_1786734278720_0.9561898195989837","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bestikk/changelog","version":"1.0.1","keywords":["changelog","keepachangelog","asciidoc","downdoc","release","cli"],"author":{"name":"Guillaume Grossetie"},"license":"MIT","_id":"@bestikk/changelog@1.0.1","maintainers":[{"name":"ggrossetie","email":"ggrossetie@gmail.com"}],"homepage":"https://github.com/bestikk/bestikk-changelog#readme","bugs":{"url":"https://github.com/bestikk/bestikk-changelog/issues"},"bin":{"bestikk-changelog":"bin/cli.js"},"dist":{"shasum":"b8490424fedf93a15f88caf9cb36ca348b8dbf24","tarball":"https://registry.npmjs.org/@bestikk/changelog/-/changelog-1.0.1.tgz","fileCount":8,"integrity":"sha512-GC1jUrtTlnAgNYxEkNe7NYo+Doyi8a+a+cEPlVxPYJjBxFHB3TMaAWxvxAFkjjFQs3lywKl/7/A5T02Ng3X4Zw==","signatures":[{"sig":"MEUCIQCB1YSDANdnIPzEziRk6uN9JQ/pZC230In1AwzPFTWxUgIgdaj7pqPGYA1Zh8zuc9eqioOwHesHGk+LleSoTb7JDBw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22608},"main":"index.js","type":"module","engines":{"node":">=18"},"gitHead":"c346aeccd8e04edc1acbe390db2072d11ae81b6b","scripts":{"lint":"biome check .","test":"node --test","format":"biome format --write .","lint:fix":"biome check --write .","postpublish":"downdoc --postpublish README.adoc","prepublishOnly":"downdoc --prepublish README.adoc"},"_npmUser":{"name":"ggrossetie","email":"ggrossetie@gmail.com"},"repository":{"url":"git+https://github.com/bestikk/bestikk-changelog.git","type":"git"},"_npmVersion":"11.12.1","description":"Manage a Keep a Changelog changelog (AsciiDoc or Markdown): roll the Unreleased section into a dated release, and extract a release as Markdown release notes.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"@biomejs/biome":"2.5.7"},"optionalDependencies":{"downdoc":"^1.1.0-stable"},"_npmOperationalInternal":{"tmp":"tmp/changelog_1.0.1_1786735858416_0.5069843505315164","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bestikk/changelog","version":"1.0.2","description":"Manage a Keep a Changelog changelog (AsciiDoc or Markdown): roll the Unreleased section into a dated release, and extract a release as Markdown release notes.","type":"module","main":"index.js","bin":{"bestikk-changelog":"bin/cli.js"},"engines":{"node":">=18"},"scripts":{"test":"node --test","lint":"biome check .","lint:fix":"biome check --write .","format":"biome format --write .","prepublishOnly":"downdoc --prepublish README.adoc","postpublish":"downdoc --postpublish README.adoc"},"repository":{"type":"git","url":"git+https://github.com/bestikk/bestikk-changelog.git"},"keywords":["changelog","keepachangelog","asciidoc","downdoc","release","cli"],"author":{"name":"Guillaume Grossetie"},"license":"MIT","bugs":{"url":"https://github.com/bestikk/bestikk-changelog/issues"},"homepage":"https://github.com/bestikk/bestikk-changelog#readme","optionalDependencies":{"downdoc":"^1.1.0-stable"},"devDependencies":{"@biomejs/biome":"2.5.7"},"gitHead":"46caefd7d76d68c725f24d59bd0df6ed86373505","_id":"@bestikk/changelog@1.0.2","_nodeVersion":"22.23.2","_npmVersion":"12.0.2","dist":{"integrity":"sha512-DmvY6wj2QT2lsMteJf0Pq/bYjd1Wk7uvLm96sR8fHn+bHGT2I/hNB5hHLC6NpjJmWkfmXZZFw83nsltGFI2hqQ==","shasum":"20978fcf6611050d1fee10293b56b799567f453f","tarball":"https://registry.npmjs.org/@bestikk/changelog/-/changelog-1.0.2.tgz","fileCount":8,"unpackedSize":22608,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bestikk%2fchangelog@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC8xZM9jzTd7RCSXSuwwz/vGx6ulWXhsH05ds/juTRa2AIgYNh+apAZQuKnmaH3TG3j20lcmLQnEYPhRPkpMvLPg+I="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e184b7f1-37dc-4f06-998c-9b0cd9d08daf"}},"directories":{},"maintainers":[{"name":"ggrossetie","email":"ggrossetie@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/changelog_1.0.2_1786735932001_0.7496889252201269"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T19:04:38.529Z","modified":"2026-08-14T19:32:12.550Z","1.0.0":"2026-08-14T19:04:38.860Z","1.0.1":"2026-08-14T19:30:58.720Z","1.0.2":"2026-08-14T19:32:12.137Z"},"bugs":{"url":"https://github.com/bestikk/bestikk-changelog/issues"},"author":{"name":"Guillaume Grossetie"},"license":"MIT","homepage":"https://github.com/bestikk/bestikk-changelog#readme","keywords":["changelog","keepachangelog","asciidoc","downdoc","release","cli"],"repository":{"type":"git","url":"git+https://github.com/bestikk/bestikk-changelog.git"},"description":"Manage a Keep a Changelog changelog (AsciiDoc or Markdown): roll the Unreleased section into a dated release, and extract a release as Markdown release notes.","maintainers":[{"name":"ggrossetie","email":"ggrossetie@gmail.com"}],"readme":"# bestikk-changelog\n\nManage a [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) style changelog, in AsciiDoc or Markdown: roll the \"Unreleased\" section into a dated release, and extract a release section as Markdown release notes suitable for a GitHub release.\n\n## Changelog formats\n\nTwo formats are supported, selected with the `format` option (`adoc` or `markdown`, default `adoc`) — the CLI infers it from the `--file` extension (`.md`/`.markdown` -> `markdown`, otherwise `adoc`).\n\n### `adoc` (AsciiDoc, e.g. `CHANGELOG.adoc`)\n\nConverted to Markdown via [downdoc](https://github.com/asciidoctor/downdoc), an optional dependency (see [Optional downdoc dependency](#optional-downdoc-dependency)).\n\nHeadings use the same `style` presets as the `markdown` format below (default `title-paren`), just with the AsciiDoc `==` marker instead of Markdown’s level 2 marker — both are a \"level 2\" heading in their respective syntax.\n\n```asciidoc\n= Project Changelog\n\n== Unreleased\n\n== v1.0.0 (2024-01-15)\n\nOptional summary paragraph, used as the release notes summary.\n\n=== Added\n\n* A new feature\n\n=== Fixed\n\n* A bug fix\n\n== v0.9.0 (2023-12-01)\n...\n```\n\n### `markdown` (native Markdown, e.g. `CHANGELOG.md`)\n\nUsed as-is, no conversion needed. The exact heading syntax is configurable via the `style` option (a preset name or a custom style object — see `lib/heading-styles.js`), since projects tend to spell the \"Unreleased\"/release headings slightly differently. Category sections (e.g. \"Added\", \"Fixed\", shown as a plain level 3 heading below) always use the same syntax, whatever the style.\n\n* **`keepachangelog` (default)**\\\nCanonical [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) syntax.\n\n  ```text\n  ## [Unreleased]\n  ## [<version>] - <date>\n  ```\n* **`title-paren`**\\\ne.g. [asciidoctor-emoji](https://github.com/ggrossetie/asciidoctor-emoji/blob/main/CHANGELOG.md).\n\n  ```text\n  ## Unreleased\n  ## v<version> (<date>)\n  ```\n* **`title-paren-suffix`**\\\ne.g. [asciidoctor-vscode](https://github.com/asciidoctor/asciidoctor-vscode/blob/main/CHANGELOG.md), whose release heading also allows an optional \"(qualifier)\" and a free-form \"- suffix\" (only the latter is written back, via the \"suffix\" option).\n\n  ```text\n  ## Unreleased\n  ## <version> [(qualifier)] (<date>) [- suffix]\n  ```\n\n```markdown\n# Project Changelog\n\n## [Unreleased]\n\n## [1.0.0] - 2024-01-15\n\nOptional summary paragraph, used as the release notes summary.\n\n### Added\n\n- A new feature\n\n### Fixed\n\n- A bug fix\n\n## [0.9.0] - 2023-12-01\n...\n```\n\nA convention that doesn’t fit any preset can be passed directly as a custom style object instead of a preset name:\n\n```js\nconst style = {\n  unreleasedHeading: '## TBD',\n  releaseHeadingTemplate: (version, date) => `## Release ${version} — ${date}`,\n  releaseHeadingRegex: (escapedVersion) =>\n    new RegExp(`(?:^|\\\\n)## Release ${escapedVersion} — ([^\\\\n]+)\\\\n([\\\\s\\\\S]*?)(?=\\\\n## |$)`),\n}\n\nrollUnreleased(content, '1.0.0', '2024-01-15', { format: 'markdown', style })\n```\n\n## Install\n\n```shell\nnpm install @bestikk/changelog\n```\n\n### Optional downdoc dependency\n\n`downdoc` is listed as an `optionalDependencies` and only loaded when processing the `adoc` format, so a project that only uses a Markdown changelog doesn’t need it. It is installed by default by `npm`/`npx`/`pnpm`/`yarn`; if it’s missing (e.g. installed with `--omit=optional`) and the `adoc` format is used, an explicit error tells you to install it.\n\n## CLI usage\n\n```shell\n# Roll the \"Unreleased\" section into a dated \"v1.0.0\" section\nnpx bestikk-changelog release 1.0.0\n\n# Print the \"v1.0.0\" section as Markdown release notes (for a GitHub release)\nnpx bestikk-changelog notes 1.0.0\n\n# Same, for a Markdown changelog (format inferred from the .md extension)\nnpx bestikk-changelog release 1.0.0 --file CHANGELOG.md\nnpx bestikk-changelog notes 1.0.0 --file CHANGELOG.md\n```\n\nBoth commands accept `--file <path>` (default: `CHANGELOG.adoc`), `--format <adoc|markdown>` (default: inferred from `--file`), and `--style <name>` (default `keepachangelog` for `markdown`, `title-paren` for `adoc`; see the styles above).\n`release` accepts `--date <YYYY-MM-DD>` (default: today) and `--suffix <text>` (appended to the release heading, used by the `title-paren-suffix` style, e.g. `--suffix \"- @octocat\"`).\n`notes` accepts `--author <name>` (default: `$GITHUB_ACTOR` or the tag’s commit author), `--previous-tag <tag>` (default: the tag before `v<version>`), and `--repo-url <url>` (default: inferred from the `origin` git remote) — used to link the full diff between releases.\n\n## Library usage\n\n```js\nimport { rollUnreleased, extractReleaseNotes } from '@bestikk/changelog'\nimport { readFileSync, writeFileSync } from 'node:fs'\n\nconst content = readFileSync('CHANGELOG.adoc', 'utf8')\n\n// Roll \"Unreleased\" into \"v1.0.0 (2024-01-15)\" (format defaults to \"adoc\")\nwriteFileSync('CHANGELOG.adoc', rollUnreleased(content, '1.0.0', '2024-01-15'))\n\n// Extract \"v1.0.0\" as Markdown release notes\nconst notes = await extractReleaseNotes(content, '1.0.0', {\n  author: 'octocat',\n  previousTag: 'v0.9.0',\n  repoUrl: 'https://github.com/example/example',\n})\n```\n\nPass `{ format: 'markdown' }` as the last argument to work with a native Markdown file instead, and `{ format: 'markdown', style: 'title-paren' }` (or another preset, or a custom style object) to match its heading syntax.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}