Update documentation

vweevers · Sep 4, 2019 · dc5b671 · dc5b671
1 parent cee5001
commit dc5b671
Show file tree

Hide file tree

Showing 5 changed files with 173 additions and 42 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+## 1.2.0 - 2019-08-11
+
+## 1.1.1 - 2019-08-09
+
+## 1.1.0 - 2019-08-09
+
+## 1.0.0 - 2019-07-12
+
+## 0.1.0 - 2018-11-24
+
+## 0.0.2 - 2018-06-24
+
+## 0.0.1 - 2018-06-23
+
+:seedling: Initial release.
diff --git a/README.md b/README.md
@@ -7,23 +7,35 @@
 [![node](https://img.shields.io/node/v/hallmark.svg)](https://www.npmjs.org/package/hallmark)
 [![Travis build status](https://img.shields.io/travis/vweevers/hallmark.svg?label=travis)](http://travis-ci.org/vweevers/hallmark)
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
-![Markdown Style Guide](https://img.shields.io/badge/md_style-hallmark-brightgreen.svg)
+[![Markdown Style Guide](https://img.shields.io/badge/md_style-hallmark-brightgreen.svg)](https://www.npmjs.org/package/hallmark)
 
 ## Table of Contents
 
 <details><summary>Click to expand</summary>
 
-- [Usage](#usage)
+- [Why](#why)
+- [Quick Start](#quick-start)
+- [What You Might Do](#what-you-might-do)
 - [Requirements](#requirements)
-- [Opt-in Features](#opt-in-features)
 - [Rules](#rules)
+- [Usage](#usage)
+- [Package Options](#package-options)
+- [Opt-in Features](#opt-in-features)
 - [Reporters](#reporters)
 - [Install](#install)
 - [License](#license)
 
 </details>
 
-## Usage
+## 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](https://keepachangelog.com/en/1.0.0/), and more.
+- **Catch style issues & mistakes early.** Save code review time by eliminating back-and-forth between reviewer & contributor.
+
+## Quick Start
 
 Lint `*.md` files:
 
@@ -43,15 +55,122 @@ Lint and fix custom files:
 hallmark --fix CHANGELOG.md docs/*.md
 ```
 
+## What You Might Do
+
+Add `hallmark` to your `package.json`:
+
+```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
 
 - A `package.json` must exist, with a [`repository`](https://docs.npmjs.com/files/package.json#repository) property
 - The working directory must be a git repository.
 
+## Rules
+
+- [Insert links to GitHub issues, PRs and usernames](https://www.npmjs.com/package/remark-github) (not linted yet)
+- [Collapse a Table of Contents if it exists](https://www.npmjs.com/package/remark-collapse) (not linted)
+- [Fenced code blocks](https://www.npmjs.com/package/remark-lint-code-block-style)
+- [End file with newline](https://www.npmjs.com/package/remark-lint-final-newline)
+- No dead links, references and definitions:
+  - [No dead internal links](https://www.npmjs.com/package/remark-validate-links)
+  - [No references to undefined definitions](https://www.npmjs.com/package/remark-lint-no-undefined-references)
+  - [No unused definitions](https://www.npmjs.com/package/remark-lint-no-unused-definitions)
+  - [No duplicate definitions](https://www.npmjs.com/package/remark-lint-no-duplicate-definitions)
+  - [Definition labels must be lowercase](https://www.npmjs.com/package/remark-lint-definition-case)
+- No more spaces than needed:
+  - [Indent list items with a single space (`-  item`)](https://www.npmjs.com/package/remark-lint-list-item-indent)
+  - [Indent blockquote content with a single space](https://www.npmjs.com/package/remark-lint-blockquote-indentation)
+  - [Checkboxes must be followed by a single space](https://www.npmjs.com/package/remark-lint-checkbox-content-indent)
+  - [No indentation before list item bullets](https://www.npmjs.com/package/remark-lint-list-item-bullet-indent)
+  - [No unneeded padding around heading content](https://www.npmjs.com/package/remark-lint-no-heading-content-indent)
+  - [No more than two spaces to create a hard break](https://www.npmjs.com/package/remark-lint-hard-break-spaces)
+  - [No inline padding between markers and content (`_ content _`)](https://www.npmjs.com/package/remark-lint-no-inline-padding)
+- Parsable literal URLs:
+  - [No literal URLs without angle-brackets](https://www.npmjs.com/package/remark-lint-no-literal-urls)
+  - [No angle-bracketed links (`<url>`) without protocol](https://www.npmjs.com/package/remark-lint-no-auto-link-without-protocol)
+- [No blank lines without markers (`>`) in a blockquote](https://www.npmjs.com/package/remark-lint-no-blockquote-without-marker)
+- [Table cells must be padded](https://www.npmjs.com/package/remark-lint-table-cell-padding) ([#16](https://github.com/vweevers/hallmark/issues/16))
+- [Table rows must be fenced with pipes](https://www.npmjs.com/package/remark-lint-table-pipes)
+- [Checkboxes must use `x` as marker](https://www.npmjs.com/package/remark-lint-checkbox-character-style)
+
+## Usage
+
+`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.
+
+Options:
+
+- `--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](#package-options).
+- `--help`: print usage and exit
+- `--version`: print version and exit
+- `--report <reporter>`: see [Reporters](#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:
+
+```json
+{
+  "name": "my-awesome-package",
+  "hallmark": {
+    "ignore": [
+      "CONTRIBUTING.md"
+    ],
+    "validateLinks": false
+  }
+}
+```
+
+### `ignore`
+
+A string or array of files to ignore. Merged with `--ignore / -i` if any (see [Usage](#usage)).
+
+### `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`](https://github.com/vweevers/hallmark/commit/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](https://github.com/vweevers/hallmark/issues/36)).
+
+### `contributors`
+
+String or array. See [Contributors Table](#contributors-table) for details. Aliased as `community`. Set to `false` to disable this feature entirely.
+
 ## Opt-in Features
 
 ### Table of Contents
 
+_Note: this feature is likely to change ([#36](https://github.com/vweevers/hallmark/issues/36))._
+
 Add this heading to a markdown file:
 
 ```markdown
@@ -62,6 +181,8 @@ 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](https://github.com/vweevers/hallmark/issues/38))._
+
 Add this heading to an otherwise empty `CONTRIBUTORS.md`:
 
 ```markdown
@@ -74,7 +195,7 @@ 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 `hallmark.contributors` (aliased as `hallmark.community`) to your `package.json`:
+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](#package-options):
 
 ```json
 "hallmark": {
@@ -94,34 +215,6 @@ Where `contributors` is either:
 
 Alternatively, put the metadata in the [`author` or `contributors` fields](https://docs.npmjs.com/files/package.json#people-fields-author-contributors) in `package.json`. For details, please see [`remark-git-contributors`](https://github.com/remarkjs/remark-git-contributors#metadata).
 
-## Rules
-
-- [Insert links to GitHub issues, PRs and usernames](https://www.npmjs.com/package/remark-github) (not linted)
-- [Collapse a Table of Contents if it exists](https://www.npmjs.com/package/remark-collapse) (not linted)
-- [Fenced code blocks](https://www.npmjs.com/package/remark-lint-code-block-style)
-- [End file with newline](https://www.npmjs.com/package/remark-lint-final-newline)
-- No dead links, references and definitions:
-  - [No dead internal links](https://www.npmjs.com/package/remark-validate-links)
-  - [No references to undefined definitions](https://www.npmjs.com/package/remark-lint-no-undefined-references)
-  - [No unused definitions](https://www.npmjs.com/package/remark-lint-no-unused-definitions)
-  - [No duplicate definitions](https://www.npmjs.com/package/remark-lint-no-duplicate-definitions)
-  - [Definition labels must be lowercase](https://www.npmjs.com/package/remark-lint-definition-case)
-- No more spaces than needed:
-  - [Indent list items with a single space (`-  item`)](https://www.npmjs.com/package/remark-lint-list-item-indent)
-  - [Indent blockquote content with a single space](https://www.npmjs.com/package/remark-lint-blockquote-indentation)
-  - [Checkboxes must be followed by a single space](https://www.npmjs.com/package/remark-lint-checkbox-content-indent)
-  - [No indentation before list item bullets](https://www.npmjs.com/package/remark-lint-list-item-bullet-indent)
-  - [No unneeded padding around heading content](https://www.npmjs.com/package/remark-lint-no-heading-content-indent)
-  - [No more than two spaces to create a hard break](https://www.npmjs.com/package/remark-lint-hard-break-spaces)
-  - [No inline padding between markers and content (`_ content _`)](https://www.npmjs.com/package/remark-lint-no-inline-padding)
-- Parsable literal URLs:
-  - [No literal URLs without angle-brackets](https://www.npmjs.com/package/remark-lint-no-literal-urls)
-  - [No angle-bracketed links (`<url>`) without protocol](https://www.npmjs.com/package/remark-lint-no-auto-link-without-protocol)
-- [No blank lines without markers (`>`) in a blockquote](https://www.npmjs.com/package/remark-lint-no-blockquote-without-marker)
-- [Table cells must be padded](https://www.npmjs.com/package/remark-lint-table-cell-padding) ([#16](https://github.com/vweevers/hallmark/issues/16))
-- [Table rows must be fenced with pipes](https://www.npmjs.com/package/remark-lint-table-pipes)
-- [Checkboxes must use `x` as marker](https://www.npmjs.com/package/remark-lint-checkbox-character-style)
-
 ## Reporters
 
 Various reporters are available:

diff --git a/USAGE b/USAGE
@@ -1,14 +1,15 @@
-Usage: hallmark [options] [path | glob ...]
+Usage: hallmark [options] [pattern ...]
 
   Markdown Style Guide, with linter and automatic fixer.
 
 Options:
 
-      --fix                 fix problems (modifies files in place)
-  -h  --help                output usage information
-  -v  --version             output version number
-      --report <reporter>   specify reporter
-      --[no-]color          force color in report (detected by default)
+      --fix                 Fix issues. Modifies files in place.
+  -i  --ignore <pattern>    Files to ignore. Repeat to specify multiple patterns
+  -h  --help                Print usage and exit
+  -v  --version             Print version and exit
+      --report <reporter>   Specify reporter
+      --[no-]color          Force color in report (detected by default)
 
 Examples:
 

diff --git a/options.js b/options.js
@@ -20,7 +20,9 @@ module.exports = function (argv, packageOpts, files, cwd, repository) {
   }
 
   const fix = argv.fix
-  const contributors = packageOpts.community || packageOpts.contributors || null
+  const contributors = 'contributors' in packageOpts
+    ? packageOpts.contributors
+    : packageOpts.community
 
   return {
     processor,
@@ -32,7 +34,10 @@ module.exports = function (argv, packageOpts, files, cwd, repository) {
     reporterOptions,
     plugins: [
       // Skip updating contributors table in lint mode
-      fix ? [require('remark-git-contributors'), { contributors }] : null,
+      fix && contributors !== false ? [require('remark-git-contributors'), {
+        contributors: contributors || null
+      }] : null,
+
       [require('remark-github'), { repository }],
 
       // TODO: https://github.com/vweevers/hallmark/issues/36

diff --git a/package.json b/package.json
@@ -7,7 +7,8 @@
   "bin": "cli.js",
   "scripts": {
     "test": "standard && node cli.js && node test.js",
-    "hallmark": "node cli.js --fix"
+    "hallmark": "node cli.js --fix",
+    "check-licenses": "npm-consider install --test --production"
   },
   "dependencies": {
     "deglob": "~4.0.0",
@@ -47,6 +48,7 @@
   "devDependencies": {
     "git-pull-or-clone": "^1.3.0",
     "level-community": "^3.0.0",
+    "npm-consider": "^1.7.0",
     "rimraf": "^3.0.0",
     "standard": "^14.0.0",
     "tape": "^4.10.2",
@@ -79,5 +81,16 @@
   ],
   "engines": {
     "node": ">=6"
+  },
+  "hallmark": {
+    "contributors": false
+  },
+  "config": {
+    "allowedLicenseTypes": [
+      "publicDomain",
+      "permissive",
+      "protective",
+      "uncategorized"
+    ]
   }
 }