Markdown Style Guide, with linter and automatic fixer
Last updated 2 months ago by vweevers .
GPL-3.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install hallmark 
SYNC missed versions from official npm registry.


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

npm status node Travis build status JavaScript Style Guide Markdown Style Guide

Table of Contents

<summary>Click to expand</summary>


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 CHANGELOG.md following Keep A 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:


Lint and fix:

hallmark --fix

Lint and fix custom files:

hallmark --fix CHANGELOG.md docs/*.md

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
  75:27-75:42  warning  Found reference to undefined definition  no-undefined-references  remark-lint

‼ 1 warning


  • A package.json must exist, with a repository property
  • The working directory must be a git repository.



hallmark [options] [pattern ...]

Lint or fix files in the current working directory. By default hallmark includes files matching *.md. Pass one or more glob patterns to override this. A pattern can either be a path to a file or a glob pattern. Files matching .gitignore patterns are ignored. To ignore additional files, use the --ignore / -i option.


  • --fix: fix issues. Modifies files in place.
  • --ignore / -i <pattern>: files to ignore. Repeat to specify multiple patterns (e.g. -i a.md -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)

Package Options

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

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


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


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).


String or array. See Contributors Table for details. Aliased as community. Set to false to disable this feature entirely.


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.

Contributors Table

Note: this feature might get removed in a next major version (#38).

Add this heading to an otherwise empty CONTRIBUTORS.md:

# Contributors

Or this heading to a README.md:

## Contributors

Running hallmark --fix will then render contributors from git history to a markdown table. To add links to GitHub and social profiles of contributors, add the contributors Package Option:

"hallmark": {
  "contributors": [{
    "name": "Sara",
    "email": "sara@example.com",
    "github": "sara",
    "twitter": "sara"

Where contributors is either:

  • An array in the form of [{ email, name, … }, … ];
  • A module id or path to a file that exports contributors or { contributors }.

Alternatively, put the metadata in the author or contributors fields in package.json. For details, please see remark-git-contributors.


Various 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 ]


With npm do:

npm install hallmark --save-dev


GPL-3.0 © 2018-present Vincent Weevers.

Current Tags

  • 2.1.0                                ...           latest (2 months ago)

9 Versions

  • 2.1.0                                ...           2 months ago
  • 2.0.0                                ...           a year ago
  • 1.2.0                                ...           a year ago
  • 1.1.1                                ...           a year ago
  • 1.1.0                                ...           a year ago
  • 1.0.0                                ...           a year ago
  • 0.1.0                                ...           2 years ago
  • 0.0.2                                ...           2 years ago
  • 0.0.1                                ...           2 years ago

Copyright 2014 - 2016 © taobao.org |