markdownlint 0.20.0 → 0.20.4

package/README.md

@@ -1,868 +1,881 @@
-# markdownlint
-
-> A Node.js style checker and lint tool for Markdown/CommonMark files.
-
-[![npm version][npm-image]][npm-url]
-[![CI Status][ci-image]][ci-url]
-[![License][license-image]][license-url]
-
-## Install
-
-```shell
-npm install markdownlint --save-dev
-```
-
-## Overview
-
-The [Markdown](https://en.wikipedia.org/wiki/Markdown) markup language is
-designed to be easy to read, write, and understand. It succeeds - and its
-flexibility is both a benefit and a drawback. Many styles are possible, so
-formatting can be inconsistent. Some constructs don't work well in all
-parsers and should be avoided. The [CommonMark](https://commonmark.org/)
-specification standardizes parsers - but not authors.
-
-`markdownlint` is a
-[static analysis](https://en.wikipedia.org/wiki/Static_program_analysis)
-tool for [Node.js](https://nodejs.org/) with a library of rules
-to enforce standards and consistency for Markdown files. It was
-inspired by - and heavily influenced by - Mark Harrison's
-[markdownlint](https://github.com/markdownlint/markdownlint) for
-[Ruby](https://www.ruby-lang.org/). The initial rules, rule documentation,
-and test cases came directly from that project.
-
-### Related
-
-* [markdownlint-cli command-line interface for Node.js](https://github.com/igorshubovych/markdownlint-cli)
-* [grunt-markdownlint for the Grunt task runner](https://github.com/sagiegurari/grunt-markdownlint)
-* [vscode-markdownlint extension for VS Code](https://marketplace.visualstudio.com/items/DavidAnson.vscode-markdownlint)
-* [Sublime Text markdownlint for Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
-* [linter-node-markdownlint extension for Atom](https://atom.io/packages/linter-node-markdownlint)
-* [coc-markdownlint extension for Vim/Neovim](https://github.com/fannheyward/coc-markdownlint)
-* [markdownlint/mdl gem for Ruby](https://rubygems.org/gems/mdl)
-* [Cake.Markdownlint addin for Cake build automation system](https://github.com/cake-contrib/Cake.Markdownlint)
-
-## Demonstration
-
-[`markdownlint` demo](https://dlaa.me/markdownlint/), an interactive, in-browser
-playground for learning and exploring.
-
-## Rules / Aliases
-
-* **[MD001](doc/Rules.md#md001)** *heading-increment/header-increment* - Heading levels should only increment by one level at a time
-* ~~**[MD002](doc/Rules.md#md002)** *first-heading-h1/first-header-h1* - First heading should be a top level heading~~
-* **[MD003](doc/Rules.md#md003)** *heading-style/header-style* - Heading style
-* **[MD004](doc/Rules.md#md004)** *ul-style* - Unordered list style
-* **[MD005](doc/Rules.md#md005)** *list-indent* - Inconsistent indentation for list items at the same level
-* ~~**[MD006](doc/Rules.md#md006)** *ul-start-left* - Consider starting bulleted lists at the beginning of the line~~
-* **[MD007](doc/Rules.md#md007)** *ul-indent* - Unordered list indentation
-* **[MD009](doc/Rules.md#md009)** *no-trailing-spaces* - Trailing spaces
-* **[MD010](doc/Rules.md#md010)** *no-hard-tabs* - Hard tabs
-* **[MD011](doc/Rules.md#md011)** *no-reversed-links* - Reversed link syntax
-* **[MD012](doc/Rules.md#md012)** *no-multiple-blanks* - Multiple consecutive blank lines
-* **[MD013](doc/Rules.md#md013)** *line-length* - Line length
-* **[MD014](doc/Rules.md#md014)** *commands-show-output* - Dollar signs used before commands without showing output
-* **[MD018](doc/Rules.md#md018)** *no-missing-space-atx* - No space after hash on atx style heading
-* **[MD019](doc/Rules.md#md019)** *no-multiple-space-atx* - Multiple spaces after hash on atx style heading
-* **[MD020](doc/Rules.md#md020)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style heading
-* **[MD021](doc/Rules.md#md021)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style heading
-* **[MD022](doc/Rules.md#md022)** *blanks-around-headings/blanks-around-headers* - Headings should be surrounded by blank lines
-* **[MD023](doc/Rules.md#md023)** *heading-start-left/header-start-left* - Headings must start at the beginning of the line
-* **[MD024](doc/Rules.md#md024)** *no-duplicate-heading/no-duplicate-header* - Multiple headings with the same content
-* **[MD025](doc/Rules.md#md025)** *single-title/single-h1* - Multiple top level headings in the same document
-* **[MD026](doc/Rules.md#md026)** *no-trailing-punctuation* - Trailing punctuation in heading
-* **[MD027](doc/Rules.md#md027)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
-* **[MD028](doc/Rules.md#md028)** *no-blanks-blockquote* - Blank line inside blockquote
-* **[MD029](doc/Rules.md#md029)** *ol-prefix* - Ordered list item prefix
-* **[MD030](doc/Rules.md#md030)** *list-marker-space* - Spaces after list markers
-* **[MD031](doc/Rules.md#md031)** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines
-* **[MD032](doc/Rules.md#md032)** *blanks-around-lists* - Lists should be surrounded by blank lines
-* **[MD033](doc/Rules.md#md033)** *no-inline-html* - Inline HTML
-* **[MD034](doc/Rules.md#md034)** *no-bare-urls* - Bare URL used
-* **[MD035](doc/Rules.md#md035)** *hr-style* - Horizontal rule style
-* **[MD036](doc/Rules.md#md036)** *no-emphasis-as-heading/no-emphasis-as-header* - Emphasis used instead of a heading
-* **[MD037](doc/Rules.md#md037)** *no-space-in-emphasis* - Spaces inside emphasis markers
-* **[MD038](doc/Rules.md#md038)** *no-space-in-code* - Spaces inside code span elements
-* **[MD039](doc/Rules.md#md039)** *no-space-in-links* - Spaces inside link text
-* **[MD040](doc/Rules.md#md040)** *fenced-code-language* - Fenced code blocks should have a language specified
-* **[MD041](doc/Rules.md#md041)** *first-line-heading/first-line-h1* - First line in file should be a top level heading
-* **[MD042](doc/Rules.md#md042)** *no-empty-links* - No empty links
-* **[MD043](doc/Rules.md#md043)** *required-headings/required-headers* - Required heading structure
-* **[MD044](doc/Rules.md#md044)** *proper-names* - Proper names should have the correct capitalization
-* **[MD045](doc/Rules.md#md045)** *no-alt-text* - Images should have alternate text (alt text)
-* **[MD046](doc/Rules.md#md046)** *code-block-style* - Code block style
-* **[MD047](doc/Rules.md#md047)** *single-trailing-newline* - Files should end with a single newline character
-* **[MD048](doc/Rules.md#md048)** *code-fence-style* - Code fence style
-
-See [Rules.md](doc/Rules.md) for more details.
-
-~~Struck through~~ rules are deprecated, and provided for backward-compatibility.
-
-> All rules with `heading` as part of their name are also available as `header`
-> aliases (e.g. `heading-increment` is also available as `header-increment`).
-> The use of `header` is deprecated and provided for backward-compatibility.
-
-## Tags
-
-Tags group related rules and can be used to enable/disable multiple rules at once.
-
-* **accessibility** - MD045
-* **atx** - MD018, MD019
-* **atx_closed** - MD020, MD021
-* **blank_lines** - MD012, MD022, MD031, MD032, MD047
-* **blockquote** - MD027, MD028
-* **bullet** - MD004, MD005, MD006, MD007, MD032
-* **code** - MD014, MD031, MD038, MD040, MD046, MD048
-* **emphasis** - MD036, MD037
-* **hard_tab** - MD010
-* **headers** - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022, MD023,
-  MD024, MD025, MD026, MD036, MD041, MD043
-* **headings** - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022, MD023,
-  MD024, MD025, MD026, MD036, MD041, MD043
-* **hr** - MD035
-* **html** - MD033
-* **images** - MD045
-* **indentation** - MD005, MD006, MD007, MD027
-* **language** - MD040
-* **line_length** - MD013
-* **links** - MD011, MD034, MD039, MD042
-* **ol** - MD029, MD030, MD032
-* **spaces** - MD018, MD019, MD020, MD021, MD023
-* **spelling** - MD044
-* **ul** - MD004, MD005, MD006, MD007, MD030, MD032
-* **url** - MD034
-* **whitespace** - MD009, MD010, MD012, MD027, MD028, MD030, MD037, MD038, MD039
-
-## Configuration
-
-Text passed to `markdownlint` is parsed as Markdown, analyzed, and any issues reported.
-Two kinds of text are ignored:
-
-* [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments)
-* [Front matter](https://jekyllrb.com/docs/frontmatter/) (see `options.frontMatter` below)
-
-Rules can be enabled, disabled, and configured via `options.config` (described
-below) to define the expected behavior for a set of inputs. To enable or disable
-rules at a particular location within a file, add one of these markers to the
-appropriate place (HTML comments don't appear in the final markup):
-
-* Disable all rules: `<!-- markdownlint-disable -->`
-* Enable all rules: `<!-- markdownlint-enable -->`
-* Disable one or more rules by name: `<!-- markdownlint-disable MD001 MD005 -->`
-* Enable one or more rules by name: `<!-- markdownlint-enable MD001 MD005 -->`
-* Capture the current rule configuration: `<!-- markdownlint-capture -->`
-* Restore the captured rule configuration: `<!-- markdownlint-restore -->`
-
-For example:
-
-```markdown
-<!-- markdownlint-disable no-space-in-emphasis -->
-deliberate space * in * emphasis
-<!-- markdownlint-enable no-space-in-emphasis -->
-```
-
-To temporarily disable rule(s), then restore the former configuration:
-
-```markdown
-<!-- markdownlint-capture -->
-<!-- markdownlint-disable -->
-any violations you want
-<!-- markdownlint-restore -->
-```
-
-The initial configuration is captured by default (as if every document began
-with `<!-- markdownlint-capture -->`), so the pattern above can be expressed
-more simply:
-
-```markdown
-<!-- markdownlint-disable -->
-any violations you want
-<!-- markdownlint-restore -->
-```
-
-Changes take effect starting with the line a comment is on, so the following
-has no effect:
-
-```markdown
-space * in * emphasis <!-- markdownlint-disable --> <!-- markdownlint-enable -->
-```
-
-To apply changes to an entire file regardless of where the comment is located,
-the following syntax is supported:
-
-* Disable all rules: `<!-- markdownlint-disable-file -->`
-* Enable all rules: `<!-- markdownlint-enable-file -->`
-* Disable one or more rules by name: `<!-- markdownlint-disable-file MD001 -->`
-* Enable one or more rules by name: `<!-- markdownlint-enable-file MD001 -->`
-
-This can be used to "hide" `markdownlint` comments at the bottom of a file.
-
-In cases where it is desirable to change the configuration of one or more rules
-for a file, the following more advanced syntax is supported:
-
-* Confiure: `<!-- markdownlint-configure-file { options.config JSON } -->`
-
-For example:
-
-```markdown
-<!-- markdownlint-configure-file { "MD013": { "line_length": 70 } } -->
-```
-
-or
-
-```markdown
-<!-- markdownlint-configure-file
-{
-  "hr-style": {
-    "style": "---"
-  },
-  "no-trailing-spaces": false
-}
--->
-```
-
-These changes apply to the entire file regardless of where the comment is
-located. Multiple such comments (if present) are applied top-to-bottom.
-
-## API
-
-### Linting
-
-Standard asynchronous interface:
-
-```js
-/**
- * Lint specified Markdown files.
- *
- * @param {Object} options Configuration options.
- * @param {Function} callback Callback (err, result) function.
- * @returns {void}
- */
-function markdownlint(options, callback) { ... }
-```
-
-Synchronous interface (for build scripts, etc.):
-
-```js
-/**
- * Lint specified Markdown files synchronously.
- *
- * @param {Object} options Configuration options.
- * @returns {Object} Result object.
- */
-function markdownlint.sync(options) { ... }
-```
-
-#### options
-
-Type: `Object`
-
-Configures the function.
-
-##### options.customRules
-
-Type: `Array` of `Object`
-
-List of custom rules to include with the default rule set for linting.
-
-Each array element should define a rule. Rules are typically exported by another
-package, but can be defined inline.
-
-Example:
-
-```js
-const extraRules = require("extraRules");
-const options = {
-  "customRules": [ extraRules.one, extraRules.two ]
-};
-```
-
-See [CustomRules.md](doc/CustomRules.md) for details about authoring custom rules.
-
-##### options.files
-
-Type: `Array` of `String`
-
-List of files to lint.
-
-Each array element should be a single file (via relative or absolute path);
-[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the caller's
-responsibility.
-
-Example: `[ "one.md", "dir/two.md" ]`
-
-##### options.strings
-
-Type: `Object` mapping `String` to `String`
-
-Map of identifiers to strings for linting.
-
-When Markdown content is not available as files, it can be passed as strings.
-The keys of the `strings` object are used to identify each input value in the
-`result` summary.
-
-Example:
-
-```json
-{
-  "readme": "# README\n...",
-  "changelog": "# CHANGELOG\n..."
-}
-```
-
-##### options.config
-
-Type: `Object` mapping `String` to `Boolean | Object`
-
-Configures the rules to use.
-
-Object keys are rule names or aliases and values are the rule's configuration.
-The value `false` disables a rule, `true` enables its default configuration,
-and passing an object customizes its settings. Setting the special `default`
-rule to `true` or `false` includes/excludes all rules by default. Enabling or
-disabling a tag name (ex: `whitespace`) affects all rules having that tag.
-
-The `default` rule is applied first, then keys are processed in order from top
-to bottom with later values overriding earlier ones. Keys (including rule names,
-aliases, tags, and `default`) are not case-sensitive.
-
-Example:
-
-```json
-{
-  "default": true,
-  "MD003": { "style": "atx_closed" },
-  "MD007": { "indent": 4 },
-  "no-hard-tabs": false,
-  "whitespace": false
-}
-```
-
-Sets of rules (known as a "style") can be stored separately and loaded as
-[JSON](https://en.wikipedia.org/wiki/JSON).
-
-Example:
-
-```js
-const options = {
-  "files": [ "..." ],
-  "config": require("style/relaxed.json")
-};
-```
-
-See the [style](style) directory for more samples.
-
-See [markdownlint-config-schema.json](schema/markdownlint-config-schema.json)
-for the [JSON Schema](https://json-schema.org/) of the `options.config` object.
-
-For more advanced scenarios, styles can reference and extend other styles. The
-`readConfig` and `readConfigSync` functions can be used to read such styles.
-
-For example, assuming a `base.json` configuration file:
-
-```json
-{
-  "default": true
-}
-```
-
-And a `custom.json` configuration file:
-
-```json
-{
-  "extends": "base.json",
-  "line-length": false
-}
-```
-
-Then code like the following:
-
-```js
-const options = {
-  "config": markdownlint.readConfigSync("./custom.json")
-};
-```
-
-Merges `custom.json` and `base.json` and is equivalent to:
-
-```js
-const options = {
-  "config": {
-    "default": true,
-    "line-length": false
-  }
-};
-```
-
-##### options.frontMatter
-
-Type: `RegExp`
-
-Matches any [front matter](https://jekyllrb.com/docs/frontmatter/) found at the
-beginning of a file.
-
-Some Markdown content begins with metadata; the default `RegExp` for this option
-ignores common forms of "front matter". To match differently, specify a custom
-`RegExp` or use the value `null` to disable the feature.
-
-The default value:
-
-```js
-/((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$))(\r\n|\r|\n|$)/m
-```
-
-Ignores [YAML](https://en.wikipedia.org/wiki/YAML) and
-[TOML](https://en.wikipedia.org/wiki/TOML) such as:
-
-```text
----
-layout: post
-title: Title
----
-```
-
-Note: Matches must occur at the start of the file.
-
-##### options.handleRuleFailures
-
-Type: `Boolean`
-
-Catches exceptions thrown during rule processing and reports the problem as a
-rule violation.
-
-By default, exceptions thrown by rules (or the library itself) are unhandled
-and bubble up the stack to the caller in the conventional manner. By setting
-`handleRuleFailures` to `true`, exceptions thrown by failing rules will be
-handled by the library and the exception message logged as a rule violation.
-This setting can be useful in the presence of (custom) rules that encounter
-unexpected syntax and fail. By enabling this option, the linting process is
-allowed to continue and report any violations that were found.
-
-##### options.noInlineConfig
-
-Type: `Boolean`
-
-Disables the use of HTML comments like `<!-- markdownlint-disable -->` to toggle
-rules within the body of Markdown content.
-
-By default, properly-formatted inline comments can be used to create exceptions
-for parts of a document. Setting `noInlineConfig` to `true` ignores all such
-comments.
-
-##### options.resultVersion
-
-Type: `Number`
-
-Specifies which version of the `result` object to return (see the "Usage" section
-below for examples).
-
-Passing a `resultVersion` of `0` corresponds to the original, simple format where
-each error is identified by rule name and line number. *This is deprecated.*
-
-Passing a `resultVersion` of `1` corresponds to a detailed format where each error
-includes information about the line number, rule name, alias, description, as well
-as any additional detail or context that is available. *This is deprecated.*
-
-Passing a `resultVersion` of `2` corresponds to a detailed format where each error
-includes information about the line number, rule names, description, as well as any
-additional detail or context that is available. *This is the default.*
-
-Passing a `resultVersion` of `3` corresponds to the detailed version `2` format
-with additional information about how to fix automatically-fixable errors. In this
-mode, all errors that occur on each line are reported (other versions report only
-the first error for each rule).
-
-##### options.markdownItPlugins
-
-Type: `Array` of `Array` of `Function` and plugin parameters
-
-Specifies additional [markdown-it plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)
-to use when parsing input. Plugins can be used to support additional syntax and
-features for advanced scenarios.
-
-Each item in the top-level `Array` should be of the form:
-
-```js
-[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
-```
-
-#### callback
-
-Type: `Function` taking (`Error`, `Object`)
-
-Standard completion callback.
-
-#### result
-
-Type: `Object`
-
-Call `result.toString()` for convenience or see below for an example of the
-structure of the `result` object. Passing the value `true` to `toString()`
-uses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`).
-
-### Config
-
-The `options.config` configuration object is simple and can be stored in a file
-for readability and easy reuse. The `readConfig` and `readConfigSync` functions
-load configuration settings and support the `extends` keyword for referencing
-other files (see above).
-
-By default, configuration files are parsed as JSON (and named `.markdownlint.json`).
-Custom parsers can be provided to handle other formats like JSONC, YAML, and TOML.
-
-Asynchronous interface:
-
-```js
-/**
- * Read specified configuration file.
- *
- * @param {String} file Configuration file name/path.
- * @param {Array} [parsers] Optional parsing function(s).
- * @param {Function} callback Callback (err, result) function.
- * @returns {void}
- */
-function readConfig(file, parsers, callback) { ... }
-```
-
-Synchronous interface:
-
-```js
-/**
- * Read specified configuration file synchronously.
- *
- * @param {String} file Configuration file name/path.
- * @param {Array} [parsers] Optional parsing function(s).
- * @returns {Object} Configuration object.
- */
-function readConfigSync(file, parsers) { ... }
-```
-
-#### file
-
-Type: `String`
-
-Location of configuration file to read.
-
-The `file` is resolved relative to the current working directory. If an `extends`
-key is present once read, its value will be resolved as a path relative to `file`
-and loaded recursively. Settings from a file referenced by `extends` are applied
-first, then those of `file` are applied on top (overriding any of the same keys
-appearing in the referenced file).
-
-#### parsers
-
-Type: *Optional* `Array` of `Function` taking (`String`) and returning `Object`
-
-Array of functions to parse configuration files.
-
-The contents of a configuration file are passed to each parser function until one
-of them returns a value (vs. throwing an exception). Consequently, strict parsers
-should come before flexible parsers.
-
-For example:
-
-```js
-[ JSON.parse, require("toml").parse, require("js-yaml").safeLoad ]
-```
-
-#### callback
-
-Type: `Function` taking (`Error`, `Object`)
-
-Standard completion callback.
-
-#### result
-
-Type: `Object`
-
-Configuration object.
-
-## Usage
-
-Invoke `markdownlint` and use the `result` object's `toString` method:
-
-```js
-const markdownlint = require("markdownlint");
-
-const options = {
-  "files": [ "good.md", "bad.md" ],
-  "strings": {
-    "good.string": "# good.string\n\nThis string passes all rules.",
-    "bad.string": "#bad.string\n\n#This string fails\tsome rules."
-  }
-};
-
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.log(result.toString());
-  }
-});
-```
-
-Output:
-
-```text
-bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19]
-bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"]
-bad.string: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This string fails        some rules."]
-bad.string: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.string"]
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
-```
-
-Or invoke `markdownlint.sync` for a synchronous call:
-
-```js
-const result = markdownlint.sync(options);
-console.log(result.toString());
-```
-
-To examine the `result` object directly:
-
-```js
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.dir(result, { "colors": true, "depth": null });
-  }
-});
-```
-
-Output:
-
-```json
-{
-  "good.md": [],
-  "bad.md": [
-    { "lineNumber": 3,
-      "ruleNames": [ "MD010", "no-hard-tabs" ],
-      "ruleDescription": "Hard tabs",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md010",
-      "errorDetail": "Column: 17",
-      "errorContext": null,
-      "errorRange": [ 17, 1 ] },
-    { "lineNumber": 1,
-      "ruleNames": [ "MD018", "no-missing-space-atx" ],
-      "ruleDescription": "No space after hash on atx style heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md018",
-      "errorDetail": null,
-      "errorContext": "#bad.md",
-      "errorRange": [ 1, 2 ] },
-    { "lineNumber": 3,
-      "ruleNames": [ "MD018", "no-missing-space-atx" ],
-      "ruleDescription": "No space after hash on atx style heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md018",
-      "errorDetail": null,
-      "errorContext": "#This file fails\tsome rules.",
-      "errorRange": [ 1, 2 ] },
-    { "lineNumber": 1,
-      "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
-      "ruleDescription": "First line in file should be a top level heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md041",
-      "errorDetail": null,
-      "errorContext": "#bad.md",
-      "errorRange": null }
-  ]
-}
-```
-
-Integration with the [gulp](https://gulpjs.com/) build system is straightforward:
-
-```js
-const gulp = require("gulp");
-const through2 = require("through2");
-const markdownlint = require("markdownlint");
-
-gulp.task("markdownlint", function task() {
-  return gulp.src("*.md", { "read": false })
-    .pipe(through2.obj(function obj(file, enc, next) {
-      markdownlint(
-        { "files": [ file.relative ] },
-        function callback(err, result) {
-          const resultString = (result || "").toString();
-          if (resultString) {
-            console.log(resultString);
-          }
-          next(err, file);
-        });
-    }));
-});
-```
-
-Output:
-
-```text
-[00:00:00] Starting 'markdownlint'...
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
-[00:00:00] Finished 'markdownlint' after 10 ms
-```
-
-Integration with the [Grunt](https://gruntjs.com/) build system is similar:
-
-```js
-const markdownlint = require("markdownlint");
-
-module.exports = function wrapper(grunt) {
-  grunt.initConfig({
-    "markdownlint": {
-      "example": {
-        "src": [ "*.md" ]
-      }
-    }
-  });
-
-  grunt.registerMultiTask("markdownlint", function task() {
-    const done = this.async();
-    markdownlint(
-      { "files": this.filesSrc },
-      function callback(err, result) {
-        const resultString = err || ((result || "").toString());
-        if (resultString) {
-          grunt.fail.warn("\n" + resultString + "\n");
-        }
-        done(!err || !resultString);
-      });
-  });
-};
-```
-
-Output:
-
-```text
-Running "markdownlint:example" (markdownlint) task
-Warning:
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
- Use --force to continue.
-```
-
-## Browser
-
-`markdownlint` also works in the browser.
-
-Generate normal and minified scripts with:
-
-```shell
-npm run build-demo
-```
-
-Then reference `markdown-it` and `markdownlint`:
-
-```html
-<script src="demo/markdown-it.min.js"></script>
-<script src="demo/markdownlint-browser.min.js"></script>
-```
-
-And call it like so:
-
-```js
-const options = {
-  "strings": {
-    "content": "Some Markdown to lint."
-  }
-};
-const results = window.markdownlint.sync(options).toString();
-```
-
-## Examples
-
-For ideas how to integrate `markdownlint` into your workflow, refer to the following projects:
-
-* [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/) ([Search repository](https://github.com/dotnet/docs/search?q=markdownlint))
-* [ally.js](https://allyjs.io/) ([Search repository](https://github.com/medialize/ally.js/search?q=markdownlint))
-* [Boostnote](https://boostnote.io/) ([Search repository](https://github.com/BoostIO/Boostnote/search?q=markdownlint))
-* [CodiMD](https://github.com/hackmdio/codimd) ([Search repository](https://github.com/hackmdio/codimd/search?q=markdownlint))
-* [ESLint](https://eslint.org/) ([Search repository](https://github.com/eslint/eslint/search?q=markdownlint))
-* [Garden React Components](https://garden.zendesk.com/react-components/)  ([Search repository](https://github.com/zendeskgarden/react-components/search?q=markdownlint))
-* [Mocha](https://mochajs.org/) ([Search repository](https://github.com/mochajs/mocha/search?q=markdownlint))
-* [Reactable](https://glittershark.github.io/reactable/) ([Search repository](https://github.com/glittershark/reactable/search?q=markdownlint))
-* [Sinon.JS](https://sinonjs.org/) ([Search repository](https://github.com/sinonjs/sinon/search?q=markdownlint))
-* [TestCafe](https://devexpress.github.io/testcafe/) ([Search repository](https://github.com/DevExpress/testcafe/search?q=markdownlint))
-* [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/basic-types.html) ([Search repository](https://github.com/Microsoft/TypeScript-Handbook/search?q=markdownlint))
-* [V8](https://v8.dev/) ([Search repository](https://github.com/v8/v8.dev/search?q=markdownlint))
-* [webhint](https://webhint.io/) ([Search repository](https://github.com/webhintio/hint/search?q=markdownlint))
-* [webpack](https://webpack.js.org/) ([Search repository](https://github.com/webpack/webpack.js.org/search?q=markdownlint))
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
-
-## History
-
-* 0.0.1 - Initial release, includes tests MD001-MD032.
-* 0.0.2 - Improve documentation, tests, and code.
-* 0.0.3 - Add synchronous API, improve documentation and code.
-* 0.0.4 - Add tests MD033-MD040, update dependencies.
-* 0.0.5 - Add `strings` option to enable file-less scenarios, add in-browser demo.
-* 0.0.6 - Improve performance, simplify in-browser, update dependencies.
-* 0.0.7 - Add MD041, improve MD003, ignore front matter, update dependencies.
-* 0.0.8 - Support disabling/enabling rules inline, improve code fence, dependencies.
-* 0.1.0 - Add aliases, exceptions for MD033, exclusions for MD013, dependencies.
-  * 0.1.1 - Fix bug handling HTML in tables, reference markdownlint-cli.
-* 0.2.0 - Add MD042/MD043, enhance MD002/MD003/MD004/MD007/MD011/MD025/MD041, dependencies.
-* 0.3.0 - More detailed error reporting with `resultVersion`, enhance MD010/MD012/MD036,
-          fixes for MD027/MD029/MD030, include JSON schema, dependencies.
-  * 0.3.1 - Fix regressions in MD032/MD038, update dependencies.
-* 0.4.0 - Add MD044, enhance MD013/MD032/MD041/MD042/MD043, fix for MD038, dependencies.
-  * 0.4.1 - Fixes for MD038/front matter, improvements to MD044, update dependencies.
-* 0.5.0 - Add shareable configuration, `noInlineConfig` option, README links, fix MD030,
-          improve MD009/MD041, update dependencies.
-* 0.6.0 - `resultVersion` defaults to 1 (breaking change), ignore HTML comments, TOML
-          front matter, fixes for MD044, update dependencies.
-  * 0.6.1 - Update `markdown-it` versioning, exclude demo/test from publishing.
-  * 0.6.2 - Improve MD013/MD027/MD034/MD037/MD038/MD041/MD044, update dependencies.
-  * 0.6.3 - Improve highlighting for MD020.
-  * 0.6.4 - Improve MD029/MD042, update dependencies.
-* 0.7.0 - `resultVersion` defaults to 2 (breaking change), add MD045, improve MD029,
-          remove trimLeft/trimRight, split rules, refactor, update dependencies.
-* 0.8.0 - Add support for using and authoring custom rules, improve MD004/MD007/MD013,
-          add `engines` to `package.json`, refactor, update dependencies.
-  * 0.8.1 - Update item loop to be iterative, improve MD014, update dependencies.
-* 0.9.0 - Remove support for end-of-life Node versions 0.10/0.12/4, change "header" to
-          "heading" per spec (non-breaking), improve MD003/MD009/MD041, handle uncommon
-          line-break characters, refactor for ES6, update dependencies.
-* 0.10.0 - Add support for non-JSON configuration files, pass file/string name to custom
-           rules, update dependencies.
-* 0.11.0 - Improve MD005/MD024/MD029/MD038, improve custom rule example, add CONTRIBUTING.md,
-           update dependencies.
-* 0.12.0 - Add `information` link for custom rules, `markdownItPlugins` for extensibility,
-           improve MD023/MD032/MD038, update dependencies.
-* 0.13.0 - Improve MD013/MD022/MD025/MD029/MD031/MD032/MD037/MD041/, deprecate MD002,
-           improve pandoc YAML support, update dependencies.
-* 0.14.0 - Remove support for end-of-life Node version 6, introduce `markdownlint-rule-helpers`,
-           add MD046/MD047, improve MD033/MD034/MD039, improve custom rule validation and
-           in-browser demo, update dependencies.
-  * 0.14.1 - Improve MD033.
-  * 0.14.2 - Improve MD047, add `handleRuleFailures` option.
-* 0.15.0 - Add `markdownlint-capture`/`markdownlint-restore` inline comments, improve
-           MD009/MD013/MD026/MD033/MD036, update dependencies.
-* 0.16.0 - Add custom rule sample for linting code, improve MD026/MD031/MD033/MD038,
-           update dependencies.
-* 0.17.0 - Add `resultVersion` 3 to support fix information for default and custom rules,
-           add fix information for 24 rules, update newline handling to match latest
-           CommonMark specification, improve MD014/MD037/MD039, update dependencies.
-  * 0.17.1 - Fix handling of front matter by fix information.
-  * 0.17.2 - Improve MD020/MD033/MD044.
-* 0.18.0 - Add MD048/code-fence-style, add fix information for MD007/ul-indent, add
-           `markdownlint-disable-file`/`markdownlint-enable-file` inline comments, add
-           type declaration file (.d.ts) for TypeScript dependents, update schema, improve
-           MD006/MD007/MD009/MD013/MD030, update dependencies.
-* 0.19.0 - Remove support for end-of-life Node version 8, add fix information for
-           MD005/list-indent, improve MD007/MD013/MD014, deprecate MD006/ul-start-left, add
-           rationale for every rule, update test runner and code coverage, add more JSDoc
-           comments, update dependencies.
-* 0.20.0 - Add `markdownlint-configure-file` inline comment,
-           improve MD005/MD007/MD013/MD018/MD029/MD031/MD034/MD037/MD038/MD039, improve HTML
-           comment handling, update dependencies.
-
-[npm-image]: https://img.shields.io/npm/v/markdownlint.svg
-[npm-url]: https://www.npmjs.com/package/markdownlint
-[ci-image]: https://github.com/DavidAnson/markdownlint/workflows/CI/badge.svg?branch=master
-[ci-url]: https://github.com/DavidAnson/markdownlint/actions?query=branch%3Amaster
-[license-image]: https://img.shields.io/npm/l/markdownlint.svg
-[license-url]: https://opensource.org/licenses/MIT
+# markdownlint
+
+> A Node.js style checker and lint tool for Markdown/CommonMark files.
+
+[![npm version][npm-image]][npm-url]
+[![CI Status][ci-image]][ci-url]
+[![License][license-image]][license-url]
+
+## Install
+
+```shell
+npm install markdownlint --save-dev
+```
+
+## Overview
+
+The [Markdown](https://en.wikipedia.org/wiki/Markdown) markup language is
+designed to be easy to read, write, and understand. It succeeds - and its
+flexibility is both a benefit and a drawback. Many styles are possible, so
+formatting can be inconsistent. Some constructs don't work well in all
+parsers and should be avoided. The [CommonMark](https://commonmark.org/)
+specification standardizes parsers - but not authors.
+
+`markdownlint` is a
+[static analysis](https://en.wikipedia.org/wiki/Static_program_analysis)
+tool for [Node.js](https://nodejs.org/) with a library of rules
+to enforce standards and consistency for Markdown files. It was
+inspired by - and heavily influenced by - Mark Harrison's
+[markdownlint](https://github.com/markdownlint/markdownlint) for
+[Ruby](https://www.ruby-lang.org/). The initial rules, rule documentation,
+and test cases came directly from that project.
+
+### Related
+
+* CLI
+  * [markdownlint-cli command-line interface for Node.js](https://github.com/igorshubovych/markdownlint-cli)
+* GitHub
+  * [GitHub Super-Linter Action](https://github.com/github/super-linter)
+  * [GitHub Actions problem matcher for markdownlint-cli](https://github.com/xt0rted/markdownlint-problem-matcher)
+* Editor
+  * [vscode-markdownlint extension for VS Code](https://marketplace.visualstudio.com/items/DavidAnson.vscode-markdownlint)
+  * [Sublime Text markdownlint for Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
+  * [linter-node-markdownlint extension for Atom](https://atom.io/packages/linter-node-markdownlint)
+  * [coc-markdownlint extension for Vim/Neovim](https://github.com/fannheyward/coc-markdownlint)
+* Tooling
+  * [grunt-markdownlint for the Grunt task runner](https://github.com/sagiegurari/grunt-markdownlint)
+  * [Cake.Markdownlint addin for Cake build automation system](https://github.com/cake-contrib/Cake.Markdownlint)
+* Ruby
+  * [markdownlint/mdl gem for Ruby](https://rubygems.org/gems/mdl)
+
+## Demonstration
+
+[`markdownlint` demo](https://dlaa.me/markdownlint/), an interactive, in-browser
+playground for learning and exploring.
+
+## Rules / Aliases
+
+* **[MD001](doc/Rules.md#md001)** *heading-increment/header-increment* - Heading levels should only increment by one level at a time
+* ~~**[MD002](doc/Rules.md#md002)** *first-heading-h1/first-header-h1* - First heading should be a top level heading~~
+* **[MD003](doc/Rules.md#md003)** *heading-style/header-style* - Heading style
+* **[MD004](doc/Rules.md#md004)** *ul-style* - Unordered list style
+* **[MD005](doc/Rules.md#md005)** *list-indent* - Inconsistent indentation for list items at the same level
+* ~~**[MD006](doc/Rules.md#md006)** *ul-start-left* - Consider starting bulleted lists at the beginning of the line~~
+* **[MD007](doc/Rules.md#md007)** *ul-indent* - Unordered list indentation
+* **[MD009](doc/Rules.md#md009)** *no-trailing-spaces* - Trailing spaces
+* **[MD010](doc/Rules.md#md010)** *no-hard-tabs* - Hard tabs
+* **[MD011](doc/Rules.md#md011)** *no-reversed-links* - Reversed link syntax
+* **[MD012](doc/Rules.md#md012)** *no-multiple-blanks* - Multiple consecutive blank lines
+* **[MD013](doc/Rules.md#md013)** *line-length* - Line length
+* **[MD014](doc/Rules.md#md014)** *commands-show-output* - Dollar signs used before commands without showing output
+* **[MD018](doc/Rules.md#md018)** *no-missing-space-atx* - No space after hash on atx style heading
+* **[MD019](doc/Rules.md#md019)** *no-multiple-space-atx* - Multiple spaces after hash on atx style heading
+* **[MD020](doc/Rules.md#md020)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style heading
+* **[MD021](doc/Rules.md#md021)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style heading
+* **[MD022](doc/Rules.md#md022)** *blanks-around-headings/blanks-around-headers* - Headings should be surrounded by blank lines
+* **[MD023](doc/Rules.md#md023)** *heading-start-left/header-start-left* - Headings must start at the beginning of the line
+* **[MD024](doc/Rules.md#md024)** *no-duplicate-heading/no-duplicate-header* - Multiple headings with the same content
+* **[MD025](doc/Rules.md#md025)** *single-title/single-h1* - Multiple top level headings in the same document
+* **[MD026](doc/Rules.md#md026)** *no-trailing-punctuation* - Trailing punctuation in heading
+* **[MD027](doc/Rules.md#md027)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
+* **[MD028](doc/Rules.md#md028)** *no-blanks-blockquote* - Blank line inside blockquote
+* **[MD029](doc/Rules.md#md029)** *ol-prefix* - Ordered list item prefix
+* **[MD030](doc/Rules.md#md030)** *list-marker-space* - Spaces after list markers
+* **[MD031](doc/Rules.md#md031)** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines
+* **[MD032](doc/Rules.md#md032)** *blanks-around-lists* - Lists should be surrounded by blank lines
+* **[MD033](doc/Rules.md#md033)** *no-inline-html* - Inline HTML
+* **[MD034](doc/Rules.md#md034)** *no-bare-urls* - Bare URL used
+* **[MD035](doc/Rules.md#md035)** *hr-style* - Horizontal rule style
+* **[MD036](doc/Rules.md#md036)** *no-emphasis-as-heading/no-emphasis-as-header* - Emphasis used instead of a heading
+* **[MD037](doc/Rules.md#md037)** *no-space-in-emphasis* - Spaces inside emphasis markers
+* **[MD038](doc/Rules.md#md038)** *no-space-in-code* - Spaces inside code span elements
+* **[MD039](doc/Rules.md#md039)** *no-space-in-links* - Spaces inside link text
+* **[MD040](doc/Rules.md#md040)** *fenced-code-language* - Fenced code blocks should have a language specified
+* **[MD041](doc/Rules.md#md041)** *first-line-heading/first-line-h1* - First line in file should be a top level heading
+* **[MD042](doc/Rules.md#md042)** *no-empty-links* - No empty links
+* **[MD043](doc/Rules.md#md043)** *required-headings/required-headers* - Required heading structure
+* **[MD044](doc/Rules.md#md044)** *proper-names* - Proper names should have the correct capitalization
+* **[MD045](doc/Rules.md#md045)** *no-alt-text* - Images should have alternate text (alt text)
+* **[MD046](doc/Rules.md#md046)** *code-block-style* - Code block style
+* **[MD047](doc/Rules.md#md047)** *single-trailing-newline* - Files should end with a single newline character
+* **[MD048](doc/Rules.md#md048)** *code-fence-style* - Code fence style
+
+See [Rules.md](doc/Rules.md) for more details.
+
+~~Struck through~~ rules are deprecated, and provided for backward-compatibility.
+
+> All rules with `heading` as part of their name are also available as `header`
+> aliases (e.g. `heading-increment` is also available as `header-increment`).
+> The use of `header` is deprecated and provided for backward-compatibility.
+
+## Tags
+
+Tags group related rules and can be used to enable/disable multiple rules at once.
+
+* **accessibility** - MD045
+* **atx** - MD018, MD019
+* **atx_closed** - MD020, MD021
+* **blank_lines** - MD012, MD022, MD031, MD032, MD047
+* **blockquote** - MD027, MD028
+* **bullet** - MD004, MD005, MD006, MD007, MD032
+* **code** - MD014, MD031, MD038, MD040, MD046, MD048
+* **emphasis** - MD036, MD037
+* **hard_tab** - MD010
+* **headers** - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022, MD023,
+  MD024, MD025, MD026, MD036, MD041, MD043
+* **headings** - MD001, MD002, MD003, MD018, MD019, MD020, MD021, MD022, MD023,
+  MD024, MD025, MD026, MD036, MD041, MD043
+* **hr** - MD035
+* **html** - MD033
+* **images** - MD045
+* **indentation** - MD005, MD006, MD007, MD027
+* **language** - MD040
+* **line_length** - MD013
+* **links** - MD011, MD034, MD039, MD042
+* **ol** - MD029, MD030, MD032
+* **spaces** - MD018, MD019, MD020, MD021, MD023
+* **spelling** - MD044
+* **ul** - MD004, MD005, MD006, MD007, MD030, MD032
+* **url** - MD034
+* **whitespace** - MD009, MD010, MD012, MD027, MD028, MD030, MD037, MD038, MD039
+
+## Configuration
+
+Text passed to `markdownlint` is parsed as Markdown, analyzed, and any issues reported.
+Two kinds of text are ignored:
+
+* [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments)
+* [Front matter](https://jekyllrb.com/docs/frontmatter/) (see `options.frontMatter` below)
+
+Rules can be enabled, disabled, and configured via `options.config` (described
+below) to define the expected behavior for a set of inputs. To enable or disable
+rules at a particular location within a file, add one of these markers to the
+appropriate place (HTML comments don't appear in the final markup):
+
+* Disable all rules: `<!-- markdownlint-disable -->`
+* Enable all rules: `<!-- markdownlint-enable -->`
+* Disable one or more rules by name: `<!-- markdownlint-disable MD001 MD005 -->`
+* Enable one or more rules by name: `<!-- markdownlint-enable MD001 MD005 -->`
+* Capture the current rule configuration: `<!-- markdownlint-capture -->`
+* Restore the captured rule configuration: `<!-- markdownlint-restore -->`
+
+For example:
+
+```markdown
+<!-- markdownlint-disable no-space-in-emphasis -->
+deliberate space * in * emphasis
+<!-- markdownlint-enable no-space-in-emphasis -->
+```
+
+To temporarily disable rule(s), then restore the former configuration:
+
+```markdown
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+any violations you want
+<!-- markdownlint-restore -->
+```
+
+The initial configuration is captured by default (as if every document began
+with `<!-- markdownlint-capture -->`), so the pattern above can be expressed
+more simply:
+
+```markdown
+<!-- markdownlint-disable -->
+any violations you want
+<!-- markdownlint-restore -->
+```
+
+Changes take effect starting with the line a comment is on, so the following
+has no effect:
+
+```markdown
+space * in * emphasis <!-- markdownlint-disable --> <!-- markdownlint-enable -->
+```
+
+To apply changes to an entire file regardless of where the comment is located,
+the following syntax is supported:
+
+* Disable all rules: `<!-- markdownlint-disable-file -->`
+* Enable all rules: `<!-- markdownlint-enable-file -->`
+* Disable one or more rules by name: `<!-- markdownlint-disable-file MD001 -->`
+* Enable one or more rules by name: `<!-- markdownlint-enable-file MD001 -->`
+
+This can be used to "hide" `markdownlint` comments at the bottom of a file.
+
+In cases where it is desirable to change the configuration of one or more rules
+for a file, the following more advanced syntax is supported:
+
+* Configure: `<!-- markdownlint-configure-file { options.config JSON } -->`
+
+For example:
+
+```markdown
+<!-- markdownlint-configure-file { "MD013": { "line_length": 70 } } -->
+```
+
+or
+
+```markdown
+<!-- markdownlint-configure-file
+{
+  "hr-style": {
+    "style": "---"
+  },
+  "no-trailing-spaces": false
+}
+-->
+```
+
+These changes apply to the entire file regardless of where the comment is
+located. Multiple such comments (if present) are applied top-to-bottom.
+
+## API
+
+### Linting
+
+Standard asynchronous interface:
+
+```js
+/**
+ * Lint specified Markdown files.
+ *
+ * @param {Object} options Configuration options.
+ * @param {Function} callback Callback (err, result) function.
+ * @returns {void}
+ */
+function markdownlint(options, callback) { ... }
+```
+
+Synchronous interface (for build scripts, etc.):
+
+```js
+/**
+ * Lint specified Markdown files synchronously.
+ *
+ * @param {Object} options Configuration options.
+ * @returns {Object} Result object.
+ */
+function markdownlint.sync(options) { ... }
+```
+
+#### options
+
+Type: `Object`
+
+Configures the function.
+
+##### options.customRules
+
+Type: `Array` of `Object`
+
+List of custom rules to include with the default rule set for linting.
+
+Each array element should define a rule. Rules are typically exported by another
+package, but can be defined inline.
+
+Example:
+
+```js
+const extraRules = require("extraRules");
+const options = {
+  "customRules": [ extraRules.one, extraRules.two ]
+};
+```
+
+See [CustomRules.md](doc/CustomRules.md) for details about authoring custom rules.
+
+##### options.files
+
+Type: `Array` of `String`
+
+List of files to lint.
+
+Each array element should be a single file (via relative or absolute path);
+[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the caller's
+responsibility.
+
+Example: `[ "one.md", "dir/two.md" ]`
+
+##### options.strings
+
+Type: `Object` mapping `String` to `String`
+
+Map of identifiers to strings for linting.
+
+When Markdown content is not available as files, it can be passed as strings.
+The keys of the `strings` object are used to identify each input value in the
+`result` summary.
+
+Example:
+
+```json
+{
+  "readme": "# README\n...",
+  "changelog": "# CHANGELOG\n..."
+}
+```
+
+##### options.config
+
+Type: `Object` mapping `String` to `Boolean | Object`
+
+Configures the rules to use.
+
+Object keys are rule names or aliases and values are the rule's configuration.
+The value `false` disables a rule, `true` enables its default configuration,
+and passing an object customizes its settings. Setting the special `default`
+rule to `true` or `false` includes/excludes all rules by default. Enabling or
+disabling a tag name (ex: `whitespace`) affects all rules having that tag.
+
+The `default` rule is applied first, then keys are processed in order from top
+to bottom with later values overriding earlier ones. Keys (including rule names,
+aliases, tags, and `default`) are not case-sensitive.
+
+Example:
+
+```json
+{
+  "default": true,
+  "MD003": { "style": "atx_closed" },
+  "MD007": { "indent": 4 },
+  "no-hard-tabs": false,
+  "whitespace": false
+}
+```
+
+Sets of rules (known as a "style") can be stored separately and loaded as
+[JSON](https://en.wikipedia.org/wiki/JSON).
+
+Example:
+
+```js
+const options = {
+  "files": [ "..." ],
+  "config": require("style/relaxed.json")
+};
+```
+
+See the [style](style) directory for more samples.
+
+See [markdownlint-config-schema.json](schema/markdownlint-config-schema.json)
+for the [JSON Schema](https://json-schema.org/) of the `options.config` object.
+
+For more advanced scenarios, styles can reference and extend other styles. The
+`readConfig` and `readConfigSync` functions can be used to read such styles.
+
+For example, assuming a `base.json` configuration file:
+
+```json
+{
+  "default": true
+}
+```
+
+And a `custom.json` configuration file:
+
+```json
+{
+  "extends": "base.json",
+  "line-length": false
+}
+```
+
+Then code like the following:
+
+```js
+const options = {
+  "config": markdownlint.readConfigSync("./custom.json")
+};
+```
+
+Merges `custom.json` and `base.json` and is equivalent to:
+
+```js
+const options = {
+  "config": {
+    "default": true,
+    "line-length": false
+  }
+};
+```
+
+##### options.frontMatter
+
+Type: `RegExp`
+
+Matches any [front matter](https://jekyllrb.com/docs/frontmatter/) found at the
+beginning of a file.
+
+Some Markdown content begins with metadata; the default `RegExp` for this option
+ignores common forms of "front matter". To match differently, specify a custom
+`RegExp` or use the value `null` to disable the feature.
+
+The default value:
+
+```js
+/((^---\s*$[^]*?^---\s*$)|(^\+\+\+\s*$[^]*?^(\+\+\+|\.\.\.)\s*$))(\r\n|\r|\n|$)/m
+```
+
+Ignores [YAML](https://en.wikipedia.org/wiki/YAML) and
+[TOML](https://en.wikipedia.org/wiki/TOML) such as:
+
+```text
+---
+layout: post
+title: Title
+---
+```
+
+Note: Matches must occur at the start of the file.
+
+##### options.handleRuleFailures
+
+Type: `Boolean`
+
+Catches exceptions thrown during rule processing and reports the problem as a
+rule violation.
+
+By default, exceptions thrown by rules (or the library itself) are unhandled
+and bubble up the stack to the caller in the conventional manner. By setting
+`handleRuleFailures` to `true`, exceptions thrown by failing rules will be
+handled by the library and the exception message logged as a rule violation.
+This setting can be useful in the presence of (custom) rules that encounter
+unexpected syntax and fail. By enabling this option, the linting process is
+allowed to continue and report any violations that were found.
+
+##### options.noInlineConfig
+
+Type: `Boolean`
+
+Disables the use of HTML comments like `<!-- markdownlint-disable -->` to toggle
+rules within the body of Markdown content.
+
+By default, properly-formatted inline comments can be used to create exceptions
+for parts of a document. Setting `noInlineConfig` to `true` ignores all such
+comments.
+
+##### options.resultVersion
+
+Type: `Number`
+
+Specifies which version of the `result` object to return (see the "Usage" section
+below for examples).
+
+Passing a `resultVersion` of `0` corresponds to the original, simple format where
+each error is identified by rule name and line number. *This is deprecated.*
+
+Passing a `resultVersion` of `1` corresponds to a detailed format where each error
+includes information about the line number, rule name, alias, description, as well
+as any additional detail or context that is available. *This is deprecated.*
+
+Passing a `resultVersion` of `2` corresponds to a detailed format where each error
+includes information about the line number, rule names, description, as well as any
+additional detail or context that is available. *This is the default.*
+
+Passing a `resultVersion` of `3` corresponds to the detailed version `2` format
+with additional information about how to fix automatically-fixable errors. In this
+mode, all errors that occur on each line are reported (other versions report only
+the first error for each rule).
+
+##### options.markdownItPlugins
+
+Type: `Array` of `Array` of `Function` and plugin parameters
+
+Specifies additional [markdown-it plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)
+to use when parsing input. Plugins can be used to support additional syntax and
+features for advanced scenarios.
+
+Each item in the top-level `Array` should be of the form:
+
+```js
+[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
+```
+
+#### callback
+
+Type: `Function` taking (`Error`, `Object`)
+
+Standard completion callback.
+
+#### result
+
+Type: `Object`
+
+Call `result.toString()` for convenience or see below for an example of the
+structure of the `result` object. Passing the value `true` to `toString()`
+uses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`).
+
+### Config
+
+The `options.config` configuration object is simple and can be stored in a file
+for readability and easy reuse. The `readConfig` and `readConfigSync` functions
+load configuration settings and support the `extends` keyword for referencing
+other files (see above).
+
+By default, configuration files are parsed as JSON (and named `.markdownlint.json`).
+Custom parsers can be provided to handle other formats like JSONC, YAML, and TOML.
+
+Asynchronous interface:
+
+```js
+/**
+ * Read specified configuration file.
+ *
+ * @param {String} file Configuration file name/path.
+ * @param {Array} [parsers] Optional parsing function(s).
+ * @param {Function} callback Callback (err, result) function.
+ * @returns {void}
+ */
+function readConfig(file, parsers, callback) { ... }
+```
+
+Synchronous interface:
+
+```js
+/**
+ * Read specified configuration file synchronously.
+ *
+ * @param {String} file Configuration file name/path.
+ * @param {Array} [parsers] Optional parsing function(s).
+ * @returns {Object} Configuration object.
+ */
+function readConfigSync(file, parsers) { ... }
+```
+
+#### file
+
+Type: `String`
+
+Location of configuration file to read.
+
+The `file` is resolved relative to the current working directory. If an `extends`
+key is present once read, its value will be resolved as a path relative to `file`
+and loaded recursively. Settings from a file referenced by `extends` are applied
+first, then those of `file` are applied on top (overriding any of the same keys
+appearing in the referenced file).
+
+#### parsers
+
+Type: *Optional* `Array` of `Function` taking (`String`) and returning `Object`
+
+Array of functions to parse configuration files.
+
+The contents of a configuration file are passed to each parser function until one
+of them returns a value (vs. throwing an exception). Consequently, strict parsers
+should come before flexible parsers.
+
+For example:
+
+```js
+[ JSON.parse, require("toml").parse, require("js-yaml").safeLoad ]
+```
+
+#### callback
+
+Type: `Function` taking (`Error`, `Object`)
+
+Standard completion callback.
+
+#### result
+
+Type: `Object`
+
+Configuration object.
+
+## Usage
+
+Invoke `markdownlint` and use the `result` object's `toString` method:
+
+```js
+const markdownlint = require("markdownlint");
+
+const options = {
+  "files": [ "good.md", "bad.md" ],
+  "strings": {
+    "good.string": "# good.string\n\nThis string passes all rules.",
+    "bad.string": "#bad.string\n\n#This string fails\tsome rules."
+  }
+};
+
+markdownlint(options, function callback(err, result) {
+  if (!err) {
+    console.log(result.toString());
+  }
+});
+```
+
+Output:
+
+```text
+bad.string: 3: MD010/no-hard-tabs Hard tabs [Column: 19]
+bad.string: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.string"]
+bad.string: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This string fails        some rules."]
+bad.string: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.string"]
+bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
+bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
+bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
+bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
+```
+
+Or invoke `markdownlint.sync` for a synchronous call:
+
+```js
+const result = markdownlint.sync(options);
+console.log(result.toString());
+```
+
+To examine the `result` object directly:
+
+```js
+markdownlint(options, function callback(err, result) {
+  if (!err) {
+    console.dir(result, { "colors": true, "depth": null });
+  }
+});
+```
+
+Output:
+
+```json
+{
+  "good.md": [],
+  "bad.md": [
+    { "lineNumber": 3,
+      "ruleNames": [ "MD010", "no-hard-tabs" ],
+      "ruleDescription": "Hard tabs",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md010",
+      "errorDetail": "Column: 17",
+      "errorContext": null,
+      "errorRange": [ 17, 1 ] },
+    { "lineNumber": 1,
+      "ruleNames": [ "MD018", "no-missing-space-atx" ],
+      "ruleDescription": "No space after hash on atx style heading",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md018",
+      "errorDetail": null,
+      "errorContext": "#bad.md",
+      "errorRange": [ 1, 2 ] },
+    { "lineNumber": 3,
+      "ruleNames": [ "MD018", "no-missing-space-atx" ],
+      "ruleDescription": "No space after hash on atx style heading",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md018",
+      "errorDetail": null,
+      "errorContext": "#This file fails\tsome rules.",
+      "errorRange": [ 1, 2 ] },
+    { "lineNumber": 1,
+      "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
+      "ruleDescription": "First line in file should be a top level heading",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/Rules.md#md041",
+      "errorDetail": null,
+      "errorContext": "#bad.md",
+      "errorRange": null }
+  ]
+}
+```
+
+Integration with the [gulp](https://gulpjs.com/) build system is straightforward:
+
+```js
+const gulp = require("gulp");
+const through2 = require("through2");
+const markdownlint = require("markdownlint");
+
+gulp.task("markdownlint", function task() {
+  return gulp.src("*.md", { "read": false })
+    .pipe(through2.obj(function obj(file, enc, next) {
+      markdownlint(
+        { "files": [ file.relative ] },
+        function callback(err, result) {
+          const resultString = (result || "").toString();
+          if (resultString) {
+            console.log(resultString);
+          }
+          next(err, file);
+        });
+    }));
+});
+```
+
+Output:
+
+```text
+[00:00:00] Starting 'markdownlint'...
+bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
+bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
+bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
+bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
+[00:00:00] Finished 'markdownlint' after 10 ms
+```
+
+Integration with the [Grunt](https://gruntjs.com/) build system is similar:
+
+```js
+const markdownlint = require("markdownlint");
+
+module.exports = function wrapper(grunt) {
+  grunt.initConfig({
+    "markdownlint": {
+      "example": {
+        "src": [ "*.md" ]
+      }
+    }
+  });
+
+  grunt.registerMultiTask("markdownlint", function task() {
+    const done = this.async();
+    markdownlint(
+      { "files": this.filesSrc },
+      function callback(err, result) {
+        const resultString = err || ((result || "").toString());
+        if (resultString) {
+          grunt.fail.warn("\n" + resultString + "\n");
+        }
+        done(!err || !resultString);
+      });
+  });
+};
+```
+
+Output:
+
+```text
+Running "markdownlint:example" (markdownlint) task
+Warning:
+bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
+bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
+bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
+bad.md: 1: MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "#bad.md"]
+ Use --force to continue.
+```
+
+## Browser
+
+`markdownlint` also works in the browser.
+
+Generate normal and minified scripts with:
+
+```shell
+npm run build-demo
+```
+
+Then reference `markdown-it` and `markdownlint`:
+
+```html
+<script src="demo/markdown-it.min.js"></script>
+<script src="demo/markdownlint-browser.min.js"></script>
+```
+
+And call it like so:
+
+```js
+const options = {
+  "strings": {
+    "content": "Some Markdown to lint."
+  }
+};
+const results = window.markdownlint.sync(options).toString();
+```
+
+## Examples
+
+For ideas how to integrate `markdownlint` into your workflow, refer to the following projects:
+
+* [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/) ([Search repository](https://github.com/dotnet/docs/search?q=markdownlint))
+* [ally.js](https://allyjs.io/) ([Search repository](https://github.com/medialize/ally.js/search?q=markdownlint))
+* [Boostnote](https://boostnote.io/) ([Search repository](https://github.com/BoostIO/Boostnote/search?q=markdownlint))
+* [CodiMD](https://github.com/hackmdio/codimd) ([Search repository](https://github.com/hackmdio/codimd/search?q=markdownlint))
+* [ESLint](https://eslint.org/) ([Search repository](https://github.com/eslint/eslint/search?q=markdownlint))
+* [Garden React Components](https://garden.zendesk.com/react-components/)  ([Search repository](https://github.com/zendeskgarden/react-components/search?q=markdownlint))
+* [MkDocs](https://www.mkdocs.org/) ([Search repository](https://github.com/mkdocs/mkdocs/search?q=markdownlint))
+* [Mocha](https://mochajs.org/) ([Search repository](https://github.com/mochajs/mocha/search?q=markdownlint))
+* [Reactable](https://glittershark.github.io/reactable/) ([Search repository](https://github.com/glittershark/reactable/search?q=markdownlint))
+* [Sinon.JS](https://sinonjs.org/) ([Search repository](https://github.com/sinonjs/sinon/search?q=markdownlint))
+* [TestCafe](https://devexpress.github.io/testcafe/) ([Search repository](https://github.com/DevExpress/testcafe/search?q=markdownlint))
+* [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/basic-types.html) ([Search repository](https://github.com/Microsoft/TypeScript-Handbook/search?q=markdownlint))
+* [V8](https://v8.dev/) ([Search repository](https://github.com/v8/v8.dev/search?q=markdownlint))
+* [webhint](https://webhint.io/) ([Search repository](https://github.com/webhintio/hint/search?q=markdownlint))
+* [webpack](https://webpack.js.org/) ([Search repository](https://github.com/webpack/webpack.js.org/search?q=markdownlint))
+* [WordPress](https://wordpress.org/gutenberg/) ([Search repository](https://github.com/WordPress/gutenberg/search?q=markdownlint))
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+
+## History
+
+* 0.0.1 - Initial release, includes tests MD001-MD032.
+* 0.0.2 - Improve documentation, tests, and code.
+* 0.0.3 - Add synchronous API, improve documentation and code.
+* 0.0.4 - Add tests MD033-MD040, update dependencies.
+* 0.0.5 - Add `strings` option to enable file-less scenarios, add in-browser demo.
+* 0.0.6 - Improve performance, simplify in-browser, update dependencies.
+* 0.0.7 - Add MD041, improve MD003, ignore front matter, update dependencies.
+* 0.0.8 - Support disabling/enabling rules inline, improve code fence, dependencies.
+* 0.1.0 - Add aliases, exceptions for MD033, exclusions for MD013, dependencies.
+  * 0.1.1 - Fix bug handling HTML in tables, reference markdownlint-cli.
+* 0.2.0 - Add MD042/MD043, enhance MD002/MD003/MD004/MD007/MD011/MD025/MD041, dependencies.
+* 0.3.0 - More detailed error reporting with `resultVersion`, enhance MD010/MD012/MD036,
+          fixes for MD027/MD029/MD030, include JSON schema, dependencies.
+  * 0.3.1 - Fix regressions in MD032/MD038, update dependencies.
+* 0.4.0 - Add MD044, enhance MD013/MD032/MD041/MD042/MD043, fix for MD038, dependencies.
+  * 0.4.1 - Fixes for MD038/front matter, improvements to MD044, update dependencies.
+* 0.5.0 - Add shareable configuration, `noInlineConfig` option, README links, fix MD030,
+          improve MD009/MD041, update dependencies.
+* 0.6.0 - `resultVersion` defaults to 1 (breaking change), ignore HTML comments, TOML
+          front matter, fixes for MD044, update dependencies.
+  * 0.6.1 - Update `markdown-it` versioning, exclude demo/test from publishing.
+  * 0.6.2 - Improve MD013/MD027/MD034/MD037/MD038/MD041/MD044, update dependencies.
+  * 0.6.3 - Improve highlighting for MD020.
+  * 0.6.4 - Improve MD029/MD042, update dependencies.
+* 0.7.0 - `resultVersion` defaults to 2 (breaking change), add MD045, improve MD029,
+          remove trimLeft/trimRight, split rules, refactor, update dependencies.
+* 0.8.0 - Add support for using and authoring custom rules, improve MD004/MD007/MD013,
+          add `engines` to `package.json`, refactor, update dependencies.
+  * 0.8.1 - Update item loop to be iterative, improve MD014, update dependencies.
+* 0.9.0 - Remove support for end-of-life Node versions 0.10/0.12/4, change "header" to
+          "heading" per spec (non-breaking), improve MD003/MD009/MD041, handle uncommon
+          line-break characters, refactor for ES6, update dependencies.
+* 0.10.0 - Add support for non-JSON configuration files, pass file/string name to custom
+           rules, update dependencies.
+* 0.11.0 - Improve MD005/MD024/MD029/MD038, improve custom rule example, add CONTRIBUTING.md,
+           update dependencies.
+* 0.12.0 - Add `information` link for custom rules, `markdownItPlugins` for extensibility,
+           improve MD023/MD032/MD038, update dependencies.
+* 0.13.0 - Improve MD013/MD022/MD025/MD029/MD031/MD032/MD037/MD041/, deprecate MD002,
+           improve pandoc YAML support, update dependencies.
+* 0.14.0 - Remove support for end-of-life Node version 6, introduce `markdownlint-rule-helpers`,
+           add MD046/MD047, improve MD033/MD034/MD039, improve custom rule validation and
+           in-browser demo, update dependencies.
+  * 0.14.1 - Improve MD033.
+  * 0.14.2 - Improve MD047, add `handleRuleFailures` option.
+* 0.15.0 - Add `markdownlint-capture`/`markdownlint-restore` inline comments, improve
+           MD009/MD013/MD026/MD033/MD036, update dependencies.
+* 0.16.0 - Add custom rule sample for linting code, improve MD026/MD031/MD033/MD038,
+           update dependencies.
+* 0.17.0 - Add `resultVersion` 3 to support fix information for default and custom rules,
+           add fix information for 24 rules, update newline handling to match latest
+           CommonMark specification, improve MD014/MD037/MD039, update dependencies.
+  * 0.17.1 - Fix handling of front matter by fix information.
+  * 0.17.2 - Improve MD020/MD033/MD044.
+* 0.18.0 - Add MD048/code-fence-style, add fix information for MD007/ul-indent, add
+           `markdownlint-disable-file`/`markdownlint-enable-file` inline comments, add
+           type declaration file (.d.ts) for TypeScript dependents, update schema, improve
+           MD006/MD007/MD009/MD013/MD030, update dependencies.
+* 0.19.0 - Remove support for end-of-life Node version 8, add fix information for
+           MD005/list-indent, improve MD007/MD013/MD014, deprecate MD006/ul-start-left, add
+           rationale for every rule, update test runner and code coverage, add more JSDoc
+           comments, update dependencies.
+* 0.20.0 - Add `markdownlint-configure-file` inline comment, reimplement MD037,
+           improve MD005/MD007/MD013/MD018/MD029/MD031/MD034/MD038/MD039, improve HTML
+           comment handling, update dependencies.
+  * 0.20.1 - Fix regression in MD037.
+  * 0.20.2 - Fix regression in MD037, improve MD038.
+  * 0.20.3 - Fix regression in MD037, improve MD044, add automatic regression testing.
+  * 0.20.4 - Fix regression in MD037, improve MD034/MD044, improve documentation.
+
+[npm-image]: https://img.shields.io/npm/v/markdownlint.svg
+[npm-url]: https://www.npmjs.com/package/markdownlint
+[ci-image]: https://github.com/DavidAnson/markdownlint/workflows/CI/badge.svg?branch=master
+[ci-url]: https://github.com/DavidAnson/markdownlint/actions?query=branch%3Amaster
+[license-image]: https://img.shields.io/npm/l/markdownlint.svg
+[license-url]: https://opensource.org/licenses/MIT