news-fragments 4.3.0 → 4.4.2

package/CHANGELOG.md

@@ -1,4 +1,35 @@
 
+[//]: # (s-4.4.2)
+
+# [4.4.2] - (2026-06-24)
+
+[//]: # (e-4.4.2)
+
+
+[//]: # (s-4.4.1)
+
+# [4.4.1] - (2026-06-24)
+
+## Misc
+* Fix node package.
+
+[//]: # (e-4.4.1)
+
+
+[//]: # (s-4.4.0)
+
+# [4.4.0] - (2026-06-24)
+
+## Features
+* Replace dependency marked with markdown-it.
+
+## Documentation
+* Updates documentation.
+
+
+[//]: # (e-4.4.0)
+
+
 [//]: # (s-4.3.0)
 
 # [4.3.0] - (2026-04-27)

package/README.md

@@ -2,24 +2,111 @@
    <img src="./changelog.png" alt="Logo" title="Logo" />
 </p>
 
-News fragments is a plugin for [release-it](https://github.com/release-it/release-it) that helps you to generate a changelog file.
+<p align="center">
+  <a href="https://www.npmjs.com/package/news-fragments?activeTab=versions"><img src="https://img.shields.io/npm/v/news-fragments?label=version&color=blue" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/news-fragments?activeTab=versions"><img src="https://img.shields.io/npm/dw/news-fragments?color=green" alt="weekly downloads" /></a>
+  <a href="https://www.npmjs.com/package/news-fragments?activeTab=versions"><img src="https://img.shields.io/npm/l/news-fragments" alt="license" /></a>
+</p>
 
-Basically, you need to specify a folder to be your center of fragments that will generate a custom changelog when released. After that, you'll create files with the desired extension with quick messages inside that folder to better understand what will come up on the new version of your software.
+News Fragments is a plugin for [release-it](https://github.com/release-it/release-it) that generates a changelog from small "fragment" files. During development, contributors add one fragment file per change; at release time the fragments are compiled into a versioned changelog entry and then deleted automatically.
 
 ## Requirements
 
-- Use Node v22+
+- Node v22+
+- npm v10+
+
+## Installation
+
+```bash
+npm install news-fragments
+```
 
 ## Setup
 
-In [release-it](https://github.com/release-it/release-it) config at `package.json`, create a `news-fragments` key-pair to override the default config - e.g.
+Add `news-fragments` as a plugin inside your [release-it](https://github.com/release-it/release-it) configuration in `package.json`:
 
 ```json
-"plugins": {
-  "news-fragments": {}
+{
+  "release-it": {
+    "plugins": {
+      "news-fragments": {}
+    }
+  }
 }
 ```
 
+Pass any [config options](#config-params) directly in this object to override the defaults.
+
+---
+
+## Release Workflow
+
+Follow these steps every time you need to publish a new version.
+
+### 1. Create fragment files during development
+
+For each change you want to appear in the changelog, run:
+
+```bash
+news-fragments create <fragment-type> "<description>"
+```
+
+**Available fragment types** (default): `feature`, `bugfix`, `doc`, `removal`, `misc`.
+
+Examples:
+
+```bash
+news-fragments create feature "Add dark mode support"
+news-fragments create bugfix "Fix race condition on login"
+news-fragments create misc "Update dependencies"
+```
+
+Each command creates a timestamped file inside the `fragments/` folder (e.g., `fragments/1714220400000.feature`). Commit these files together with the code changes they describe.
+
+### 2. Preview the next changelog entry
+
+Before releasing, verify what the generated changelog will look like:
+
+```bash
+news-fragments preview
+```
+
+To preview an already-released version stored in `CHANGELOG.md`:
+
+```bash
+news-fragments preview -p <version>
+# e.g. news-fragments preview -p 1.2.3
+```
+
+### 3. Run the release
+
+```bash
+npm run release
+```
+
+This command triggers `release-it`, which will:
+
+1. Run the test suite (`npm test`) as a pre-release check.
+2. Prompt you to select the next version (patch / minor / major).
+3. Burn the pending fragments into `CHANGELOG.md` under the new version header and delete the fragment files.
+4. Bump the version in `package.json`.
+5. Commit, tag, and push the release.
+
+> The burn step runs automatically via the `news-fragments` plugin — you do **not** need to run `news-fragments burn` manually when using `release-it`.
+
+### Manual burn (without release-it)
+
+If you need to compile fragments into the changelog outside of `release-it`, use:
+
+```bash
+news-fragments burn <version>
+# e.g. news-fragments burn 2.0.0
+```
+
+This writes the changelog entry for `<version>` and removes all consumed fragment files.
+
+---
+
 ## Config
 
 ### Default config
@@ -28,21 +115,21 @@ In [release-it](https://github.com/release-it/release-it) config at `package.jso
 {
   "changelogFile": "CHANGELOG.md",
   "changelogDateFormat": "YYYY-MM-DD",
-  "changelogTemplate": changelogTemplate,
+  "changelogTemplate": "<built-in handlebars template>",
   "fragmentsFolder": "fragments",
   "fragmentsTypes": [
-    { "title": "Features", "extension": "feature" },
-    { "title": "Bugfixes", "extension": "bugfix" },
-    { "title": "Documentation", "extension": "doc" },
+    { "title": "Features",                  "extension": "feature" },
+    { "title": "Bugfixes",                  "extension": "bugfix"  },
+    { "title": "Documentation",             "extension": "doc"     },
     { "title": "Deprecations and Removals", "extension": "removal" },
-    { "title": "Misc", "extension": "misc" }
+    { "title": "Misc",                      "extension": "misc"    }
   ]
 }
 ```
 
 ### Default changelog template
 
-```
+```handlebars
 # [{{newVersion}}] - ({{bumpDate}})
 {{#fragments}}
 ## {{title}}
@@ -54,16 +141,39 @@ In [release-it](https://github.com/release-it/release-it) config at `package.jso
 
 ### Config params
 
-- **changelogFile**: A path to the file that will center your changelog.
-- **changelogDateFormat**: The date format that will be send to changelog template.
-- **changelogTemplate**: A [handlebars](https://www.npmjs.com/package/handlebars) template that will be used to render your changelog file content.
-- **fragmentsFolder**: A path to the folder that the fragments should be stored.
-- **fragmentsTypes**: An array containing a collection of objects with the title of changelog section and the extension of fragment types.
+| Key | Description |
+|-----|-------------|
+| `changelogFile` | Path to the changelog file. |
+| `changelogDateFormat` | [Moment.js](https://momentjs.com/docs/#/displaying/format/) date format used in the changelog header. |
+| `changelogTemplate` | A [Handlebars](https://handlebarsjs.com/) template string for each version block. |
+| `fragmentsFolder` | Path to the folder where fragment files are stored. |
+| `fragmentsTypes` | Array of `{ title, extension }` objects that define the supported fragment types and their changelog section headings. |
 
 > See this plugin in action by checking our [CHANGELOG.md](./CHANGELOG.md)
 
-## CLI
+---
+
+## CLI Reference
 
 ```bash
 news-fragments --help
 ```
+
+| Command | Description |
+|---------|-------------|
+| `news-fragments create <type> "<text>"` | Create a new fragment file of the given type. |
+| `news-fragments preview` | Print the next changelog entry to the terminal. |
+| `news-fragments preview -p <version>` | Print a previously released changelog entry. |
+| `news-fragments burn <version>` | Compile fragments into the changelog and delete them. |
+
+---
+
+## Contributing
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests (includes lint)
+npm test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "news-fragments",
-  "version": "4.3.0",
+  "version": "4.4.2",
   "description": "A release-it plugin to manipulate changelogs",
   "main": "src/index.js",
   "type": "module",
@@ -14,7 +14,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/grupoboticario/news-fragments.git"
+    "url": "git+https://github.com/grupoboticario/news-fragments.git"
   },
   "keywords": [
     "release",
@@ -53,8 +53,7 @@
     "chalk-template": "^1.1.2",
     "handlebars": "^4.7.9",
     "joi": "^18.1.2",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
+    "markdown-it": "^14.2.0",
     "meow": "^14.1.0",
     "moment": "^2.30.1",
     "release-it": "^20.0.1"

package/src/build-template.js

@@ -13,7 +13,7 @@ ${compiledTemplate}
 }
 
 export const renderTemplate = function (changelogTemplate, data, version) {
-  const compiledTemplate = Handlebars.compile(changelogTemplate);
+  const compiledTemplate = Handlebars.compile(changelogTemplate, { noEscape: true });
   return injectMetadata(compiledTemplate(data), version);
 };
 

package/src/cli/markdown-terminal.js

@@ -0,0 +1,70 @@
+import chalk from "chalk";
+import MarkdownIt from "markdown-it";
+
+const styles = {
+  firstHeading: chalk.magenta.underline.bold,
+  heading: chalk.green.bold,
+};
+
+const md = new MarkdownIt();
+
+const renderInlineToken = (token, env) => {
+  let content = token.content;
+
+  if (env.headingLevel) {
+    const prefix = `${"#".repeat(env.headingLevel)} `;
+    content = prefix + content;
+    const style =
+      env.headingLevel === 1 ? styles.firstHeading : styles.heading;
+
+    return style(content);
+  }
+
+  return content;
+};
+
+const renderTokens = (tokens, env) => {
+  let result = "";
+
+  for (const token of tokens) {
+    switch (token.type) {
+      case "heading_open":
+        env.headingLevel = Number(token.tag.slice(1));
+        break;
+      case "heading_close":
+        env.headingLevel = 0;
+        result += "\n";
+        break;
+      case "inline":
+        result += renderInlineToken(token, env);
+        break;
+      case "list_item_open":
+        result += "- ";
+        break;
+      case "list_item_close":
+        result += "\n";
+        break;
+      case "bullet_list_close":
+        result += "\n";
+        break;
+      case "paragraph_open":
+      case "paragraph_close":
+      case "bullet_list_open":
+      case "ordered_list_open":
+      case "ordered_list_close":
+        break;
+      default:
+        break;
+    }
+  }
+
+  return result;
+};
+
+export const renderMarkdownForTerminal = (source) => {
+  if (!source) {
+    return "";
+  }
+
+  return renderTokens(md.parse(source, {}), { headingLevel: 0 });
+};

package/src/cli/preview.js

@@ -1,15 +1,7 @@
-import { marked } from "marked";
-import TerminalRenderer from "marked-terminal";
-
 import { generateTemplateData, renderTemplate } from "../build-template.js";
 import { newsFragmentsUserConfig } from "../config.js";
 import { getChangelogContent, getFragments } from "../file.js";
-
-marked.setOptions({
-  renderer: new TerminalRenderer({ tab: 0 }),
-  mangle: false,
-  headerIds: false,
-});
+import { renderMarkdownForTerminal } from "./markdown-terminal.js";
 
 export const preview = function (inputs, flags) {
   if (!!flags && flags.previousVersion) {
@@ -18,7 +10,7 @@ export const preview = function (inputs, flags) {
     );
 
     const changelogContent = getChangelogContent(newsFragmentsUserConfig);
-    const previousOutput = marked(
+    const previousOutput = renderMarkdownForTerminal(
       (changelogContent.match(previousVersionRegex) || [""])[0],
     );
 
@@ -42,7 +34,7 @@ export const preview = function (inputs, flags) {
     version,
   );
 
-  const output = marked(renderedTemplate);
+  const output = renderMarkdownForTerminal(renderedTemplate);
   process.stdout.write(output);
 
   return output;