npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

hallmark

v4.2.0

Published

Markdown Style Guide, with linter and automatic fixer

Downloads

915

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

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 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:

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

  • 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

Usage

hallmark [command] [options]

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

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

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:

  • 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 CHANGELOG.md. After you tweak the release following Common Changelog you may want to run hallmark fix.

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:

  • --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": [
      "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:

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

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.

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.