Repository files navigation

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

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. Noremark plugins to manage.
• Automatically format markdown. Runhallmark fix to format markdown, wrap GitHub issues and usernames in links, autocomplete aCHANGELOG.md followingCommon Changelog and more.
• Catch style issues & mistakes early. Save code review time by eliminating back-and-forth between reviewer & contributor.

Lint*.md files:

hallmark

Fix markdown files in place:

hallmark fix

Fix custom files:

hallmark fix CHANGELOG.md docs/*.md

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

hallmark cc add minorhallmark cc add 4.2.0 --no-commits

Addhallmark to yourpackage.json:

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

Markdown is then checked automatically when you runnpm test:

$ npm testREADME.md:5:3  ⚠️  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 apackage.json with arepository property, or have a gitorigin remote

• Use- as marker for bullets of items in unordered lists (- item)
• Use_ as marker for emphasis (_emphasis_)
• Use* as marker for strong (**strong**)
• Usex as marker for checkboxes (- [x] item)
• Use backtick as marker for fenced code block
• Always use fences for code blocks
• Use--- for thematic breaks
• Insert links to GitHub issues, PRs and usernames (not linted)
• Collapse a Table of Contents if it exists (not linted)
• 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
• Tables:
  • Table cells must be padded (#16)
  • Table rows must be fenced with pipes

hallmark [command] [options]

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

Options:

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

Lint markdown files. By defaulthallmark 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 markdown files in place. The optionalfile argument is the same as onlint.

Add release(s) toCHANGELOG.md and populate it with commits. If noCHANGELOG.md file exists then it will be created. Thetarget 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 orpackage.json (whichever is greatest if found) and bump it
  • Themajor type bumps the major version (for example2.4.1 => 3.0.0);minor andpatch work the same way.
  • Thepremajor type bumps the version up to the next major version and down to a prerelease of that major version;preminor andprepatch work the same way.
  • Theprerelease type works the same asprepatch if the current version is a non-prerelease. If the current is already a prerelease then it's simply incremented (for example4.0.0-rc.2 to4.0.0-rc.3).
• Asemver-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 equals0.0.1 or1.0.0 and zero versions exist, then anotice 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 examplehallmark cc add 1.1.0 1.2.0 which acts as a shortcut forhallmark cc add 1.1.0 && hallmark cc add 1.2.0.

Works best on a linear git history without merge commits. Ifhallmark encounters other tags in the commit range it will stop there and not include further (older) commits.

Thecc add command also fixes markdown (both existing content and generated content) but only inCHANGELOG.md. After you tweak the release followingCommon Changelog you may want to runhallmark fix.

Gittrailers ("lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message") can provide structured information to the generated changelog. The following trailer keys are supported (case-insensitive):

• Category: one ofchange,addition,removal,fix, ornone. Ifnone then the commit will be excluded from the changelog. If not present then the change will be listed under Uncategorized and will require manual categorization.
• Notice: anotice for the release. If multiple commits contain a notice, they will be joined as sentences (i.e. ending with a dot) separated by a space.
• Ref,Refs,Fixes,Closes orCVE-ID: a numeric reference in the form of#N,PREFIX-N orCVE-N-N whereN is a number andPREFIX is at least 2 letters. For example#123,GH-123,JIRA-123 orCVE-2024-123. Can be repeated, either with multiple trailer lines or by separating references with a comma - e.g.Ref: #1, #2. Non-numeric references are ignored.
• Co-Authored-By: co-author in the form ofname <email>. Can be repeated.

For example, the following commit (which has Bob as git author, let's say):

Bump math-utils to 4.5.6Ref: JIRA-123Category: changeCo-Authored-By: Alice <alice@example.com>

Turns into:

##Changed- Bump math-utils to 4.5.6 (d23ba8f) (JIRA-123) (Bob, Alice)

Create aCHANGELOG.md from scratch. Inserts releases for every (semver-valid) git tag and then populates them with commits. If no git tags exist then the resultingCHANGELOG.md 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.

You can add ahallmark object to yourpackage.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"  ]}

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

Autolink custom referenceslike GitHub Pro does. Must be an object with aprefix andurl (ifautolinkReferences is not set, this feature does nothing). For example, given:

{"autolinkReferences": {"prefix":"JIRA-","url":"https://example.atlassian.net/browse/JIRA-<num>"  }}

Thenhallmark fix will transform:

###Fixed- Prevent infinite loop (JIRA-4275)

To:

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

Whilehallmark lint will warn about unlinked references.

An object containing options to be passed toremark-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 tofalse 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 tofalse to keep markdown tables compact. A temporary option until we decide on and are able to lint a style (3210a96).

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.

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

• vfile-reporter
• vfile-reporter-json
• vfile-reporter-pretty

To use a custom reporter first install it withnpm:

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

Then pass it tohallmark with or without options:

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

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

Withnpm do:

npm install hallmark --save-dev

GPL-3.0 © 2018-present Vincent Weevers.