Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Markdown Style Guide, with linter and automatic fixer.
Powered by remark.

npm status node Test JavaScript Style Guide Markdown Style Guide Common Changelog

Table of Contents

Click to expand


This module saves you time in three ways:

  • No configuration. The easiest way to enforce markdown code quality in your project. No decisions to make. No remark plugins to manage.
  • Automatically format markdown. Run hallmark fix to format markdown, wrap GitHub issues and usernames in links, autocomplete a following Common Changelog and more.
  • Catch style issues & mistakes early. Save code review time by eliminating back-and-forth between reviewer & contributor.

Quick Start

Lint *.md files:


Fix markdown files in place:

hallmark fix

Fix custom files:

hallmark fix docs/*.md

Add new minor version or existing version to changelog, optionally without content:

hallmark cc add minor
hallmark cc add 4.2.0 --no-commits

What You Might Do

Add hallmark to your package.json:

  "name": "my-awesome-package",
  "devDependencies": {
    "hallmark": "^2.0.0"
  "scripts": {
    "test": "hallmark && node my-tests.js"

Markdown is then checked automatically when you run npm test:

$ npm test
  ⚠️  5:3  Found reference to undefined definition  remark-lint:no-undefined-references

  1 warning


  • The working directory must be a git repository
  • It must either contain a package.json with a repository property, or have a git origin remote



hallmark [command] [options]

Lint or fix files in the current working directory. The default command is lint.


  • --ignore / -i <file>: file or glob pattern to ignore. Repeat to specify multiple (e.g. -i -i docs/*.md). Can also be configured via Package Options.
  • --help: print usage and exit
  • --version: print version and exit
  • --report <reporter>: see Reporters
  • --[no-]color: force color in report (detected by default)
  • --fix: backwards-compatible alias for fix command


lint [file...]

Lint markdown files. By default hallmark includes files matching *.md. To override this, provide one or more file arguments which can be file paths or glob patterns. Files matching .gitignore patterns are ignored. To ignore additional files, use the --ignore / -i option.

fix [file...]

Fix markdown files in place. The optional file argument is the same as on lint.

cc add <target...>

Add release(s) to and populate it with commits. If no file exists then it will be created. The target argument must be one of:

  • A release type: major, minor, patch, premajor, preminor, prepatch, prerelease
    • These take the current version from the semver-latest tag, release or package.json (whichever is greatest if found) and bump it
    • The major type bumps the major version (for example 2.4.1 => 3.0.0); minor and patch work the same way.
    • The premajor type bumps the version up to the next major version and down to a prerelease of that major version; preminor and prepatch work the same way.
    • The prerelease type works the same as prepatch if the current version is a non-prerelease. If the current is already a prerelease then it's simply incremented (for example 4.0.0-rc.2 to 4.0.0-rc.3).
  • A semver-valid version like 2.4.0.

If the (resulting) version is greater than the current version then commits will be taken from the semver-latest tag until HEAD. I.e. documenting a new release before it's git-tagged. If the version matches an existing tag then a release will be inserted at the appriopriate place, populated with commits between that version's tag and the one before it. I.e. documenting a past release after it's git-tagged. If the version equals 0.0.1 or 1.0.0 and zero versions exist, then a notice will be inserted (rather than commits) containing the text :seedling: Initial release..

Additional options for this command:

  • --no-commits: create an empty release.

Multiple targets can be provided, in no particular order. For example hallmark cc add 1.1.0 1.2.0 which acts as a shortcut for hallmark cc add 1.1.0 && hallmark cc add 1.2.0.

Works best on a linear git history. If hallmark encounters other tags in the commit range (which may happen if releases were made in parallel on other branches) it will stop there and not include further (older) commits.

The cc add command also fixes markdown (both existing content and generated content) but only in After you tweak the release following Common Changelog you may want to run hallmark fix.

cc init

Create a from scratch. Inserts releases for every (semver-valid) git tag and then populates them with commits. If no git tags exist then the resulting will merely have a # Changelog heading, without releases.

Additional options for this command:

  • --no-commits: create empty releases
  • --gte <version>: only include versions greater than or equal to this version
  • --lte <version>: only include versions less than or equal to this version.

Package Options

You can add a hallmark object to your package.json with additional configuration. For example:

  "name": "my-awesome-package",
  "hallmark": {
    "ignore": [

Alternatively, for use in non-node projects, place a .hallmarkrc file in the working directory or any of its parent directories:

  "ignore": [


A string or array of files to ignore. Merged with --ignore / -i if any.


Autolink custom references like GitHub Pro does. Must be an object with a prefix and url (if autolinkReferences is not set, this feature does nothing). For example, given:

  "autolinkReferences": {
    "prefix": "JIRA-",
    "url": "<num>"

Then hallmark fix will transform:

### Fixed

- Prevent infinite loop (JIRA-4275)


### Fixed

- Prevent infinite loop ([JIRA-4275](

While hallmark lint will warn about unlinked references.


An object containing options to be passed to remark-common-changelog:

  • submodules (boolean): enable experimental git submodule support. Will (upon encountering new or empty changelog entries) collect commits from submodules and list them in the changelog as <submodule>: <message>.

Boolean. Set to false to skip validating links. Useful when a markdown file uses HTML anchors, which not are not recognized as links. A temporary option until we decide whether to allow and parse those.


Boolean. Set to false to keep markdown tables compact. A temporary option until we decide on and are able to lint a style (3210a96).


Boolean. Set to false to skip generating (or replacing) a Table of Contents. A temporary option until we write a more flexible plugin (#36).


An array of extra plugins, to be applied in both lint and fix mode.


An array of extra plugins, to be applied in fix mode.

Opt-in Features

Table of Contents

Note: this feature is likely to change (#36).

Add this heading to a markdown file:

## Table of Contents

Running hallmark fix will then create or update a table of contents.


The default reporter is vfile-reporter-shiny. Various other reporters are available:

To use a custom reporter first install it with npm:

npm i vfile-reporter-json --save-dev

Then pass it to hallmark with or without options:

hallmark --report json
hallmark --report [ json --pretty ]

In the programmatic API of hallmark (which is not documented yet) the reporter can also be disabled by passing { report: false } as the options.


With npm do:

npm install hallmark --save-dev


GPL-3.0 © 2018-present Vincent Weevers.