hallmark

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

Table of Contents

Why

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:

hallmark

Fix markdown files in place:

hallmark fix

Fix custom files:

hallmark fix CHANGELOG.md docs/*.md

Add new minor version to changelog:

hallmark bump minor

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

‼ 1 warning

Requirements

• 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

Rules

• Insert links to GitHub issues, PRs and usernames (not linted yet)
• Collapse a Table of Contents if it exists (not linted)
• Fenced code blocks
• End file with newline
• No dead links, references and definitions:
  • No dead internal links
  • No references to undefined definitions
  • No unused definitions
  • No duplicate definitions
  • Definition labels must be lowercase
• No more spaces than needed:
  • Indent list items with a single space (- item)
  • Indent blockquote content with a single space
  • Checkboxes must be followed by a single space
  • No indentation before list item bullets
  • No unneeded padding around heading content
  • No more than two spaces to create a hard break
  • No inline padding between markers and content (_ content _)
• Parsable literal URLs:
  • No literal URLs without angle-brackets
  • No angle-bracketed links (<url>) without protocol
• No blank lines without markers (>) in a blockquote
• Table cells must be padded (#16)
• Table rows must be fenced with pipes
• Checkboxes must use x as marker

Usage

hallmark [command] [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. Files matching .gitignore patterns are ignored. To ignore additional files, use the --ignore / -i option.

Commands:

• lint: lint markdown files (default)
• fix: fix markdown files
• bump <target>: add new entry to changelog. Target must be a release type (major, minor, patch, premajor, preminor, prepatch, prerelease) or a version.

Options:

• --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)
• --fix: backwards-compatible alias for fix command

Package Options

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

{
  "name": "my-awesome-package",
  "hallmark": {
    "ignore": [
      "CONTRIBUTING.md"
    ]
  }
}

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

{
  "ignore": [
    "CONTRIBUTING.md"
  ]
}

ignore

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

autolinkReferences

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": "https://example.atlassian.net/browse/JIRA-<num>"
  }
}

Then hallmark fix will transform:

### Fixed

- Prevent infinite loop (JIRA-4275)

To:

### Fixed

- Prevent infinite loop ([JIRA-4275](https://example.atlassian.net/browse/JIRA-4275))

While hallmark lint will warn about unlinked references.

changelog

An object containing options to be passed to remark-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>.

validateLinks

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.

paddedTable

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

toc

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

contributors

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

plugins

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

fixers

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.

Reporters

Various reporters are available:

• vfile-reporter (default)
• vfile-reporter-json
• vfile-reporter-pretty

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 ]

Install

With npm do:

npm install hallmark --save-dev

License

GPL-3.0 © 2018-present Vincent Weevers.