remark-common-changelog

2.3.2 verified Fri May 01 auth: no javascript

A remark plugin to lint or fix a Markdown changelog according to the Common Changelog specification. Current stable version 2.3.2 (npm, 2023). ESM-only, requires Node >=12.20. It enforces changelog structure, heading format, version links, dates, release ordering, and can auto-fill empty releases with commit logs. Unlike generic Markdown linting, it specializes in changelog conventions and integrates with git history.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause Using CJS require() on an ESM-only package.

fix

Switch to ES modules: use import syntax or rename file to .mjs.

error Error: Cannot find module 'remark' ↓

cause Missing peer dependency 'remark' not installed.

fix

Run 'npm install remark' or include it in your dependencies.

error Error: Cannot find module 'to-vfile' ↓

cause Missing optional dependency used in examples.

fix

Run 'npm install to-vfile' if you are using it in your code.

error TypeError: Cannot read properties of undefined (reading 'some') ↓

cause Changelog file missing or malformed (e.g., no 'Changelog' heading).

fix

Ensure CHANGELOG.md exists and starts with '# Changelog'.

Warnings

breaking v2.0.0 broke ESM/CJS: switched to ESM-only and dropped Node <12.20. ↓

fix Update Node to >=12.20 and use import instead of require.

gotcha Changelog must start with a top-level "Changelog" heading (title rule). ↓

fix Ensure the first line is '# Changelog' or let fix mode add/update it.

gotcha Release versions must be semver-valid, no 'v' prefix. ↓

fix Use version format '1.0.0' not 'v1.0.0' in headings.

gotcha Release headings require a link reference (release-version-link-reference rule). ↓

fix Use '[1.0.0]: <url>' reference style, not inline links.

gotcha Auto-fill empty releases with commit log uses git history; may include unwanted commits. ↓

fix Manually review and edit the filled content.

Install

npm install remark-common-changelog

yarn add remark-common-changelog

pnpm add remark-common-changelog

Imports

default (changelog)

wrong

const changelog = require('remark-common-changelog')

correct

import changelog from 'remark-common-changelog'

The package is ESM-only since v2.0.0, so CJS require will fail.

remark use

wrong

remark().use(changelog) without importing remark

correct

import { remark } from 'remark'; remark().use(changelog)

Use the unified ecosystem: import remark and call .use() with the plugin.

TypeScript types
```
import type { ... } from 'remark-common-changelog'
```
TypeScript types are not explicitly documented; may rely on inferred types.

Quickstart

Lint and fix a CHANGELOG.md file using remark-common-changelog plugin with to-vfile for I/O.

import changelog from 'remark-common-changelog'
import { readSync, writeSync } from 'to-vfile'
import { remark } from 'remark'

remark()
  .use(changelog)
  .process(readSync('CHANGELOG.md'), (err, file) => {
    if (err) throw err
    writeSync(file)
  })
console.log('CHANGELOG.md linted and fixed (if fix mode enabled)')