search

vweevers / hallmark

Markdown Style Guide, with linter and automatic fixer.
GNU General Public License v3.0
30 stars 3 forks source link
documentation fixer linter markdown remark tooling

readme

hallmark

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

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

Why

This module saves you time in three ways:

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 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
README.md:5:3
  ⚠️  5:3  Found reference to undefined definition  remark-lint:no-undefined-references

  1 warning

Requirements

Rules

Usage

hallmark [command] [options]

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

Options:

Commands

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 CHANGELOG.md and populate it with commits. If no CHANGELOG.md file exists then it will be created. The target argument must be one of:

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:

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 without merge commits. If hallmark encounters other tags in the commit range 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 CHANGELOG.md. After you tweak the release following Common Changelog you may want to run hallmark fix.

Git trailers ("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):

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

Bump math-utils to 4.5.6

Ref: JIRA-123
Category: change
Co-Authored-By: Alice <alice@example.com>

Turns into:

## Changed

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

cc init

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

Additional options for this 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-common-changelog:

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

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.

Reporters

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.

Install

With npm do:

npm install hallmark --save-dev

License

GPL-3.0 © 2018-present Vincent Weevers.