markdownlint

A Node.js style checker and lint tool for Markdown/CommonMark files.

MarkdownLinter
DavidAnson/markdownlintmarkdownlint

README

markdownlint


A Node.js style checker and lint tool for Markdown/CommonMark files.


Install


  1. ```bash
  2. npm install markdownlint --save-dev
  3. ```

Overview


The 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 specification standardizes
parsers - but not authors.

markdownlint is a
static analysis
tool for Node.js 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 for
Ruby. The initial rules, rule documentation,
and test cases came directly from that project.

References


The following specifications are considered authoritative in cases of ambiguity:

- CommonMark
- GitHub Flavored Markdown Spec

Demonstration


[markdownlint demo](https://dlaa.me/markdownlint/), an interactive, in-browser
playground for learning and exploring.

Custom Rules


In addition to built-in rules, custom rules can be used to address
project-specific requirements. To find community-developed rules use
keyword markdownlint-rule on npm.
To implement your own rules, refer to CustomRules.md.

[markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule

Configuration


Text passed to markdownlint is parsed as Markdown, analyzed, and any
issues reported. Two kinds of text are ignored by most rules:

- HTML comments
- Front matter (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: ``- Enable all rules: ``- Disable all rules for the current line: ``- Disable all rules for the next line: ``- Disable one or more rules by name: ``- Enable one or more rules by name: ``
- Disable one or more rules by name for the current line:
``
- Disable one or more rules by name for the next line:
``- Capture the current rule configuration: ``- Restore the captured rule configuration: ``

For example:

  1. ```markdown
  3. space * in * emphasis
  4. ```

Or:

  1. ```markdown
  2. space * in * emphasis
  3. ```

Or:

  1. ```markdown
  3. space * in * emphasis
  5. ```

To temporarily disable rule(s), then restore the former configuration:

  1. ```markdown
  4. any violations you want
  6. ```

The initial configuration is captured by default (as if every document
began with ``), so the pattern above can
be expressed more simply:

  1. ```markdown
  3. any violations you want
  5. ```

Changes take effect starting with the line a comment is on, so the following
has no effect:

  1. ```markdown
  2. space * in * emphasis
  3. ```

To apply changes to an entire file regardless of where the comment is located,
the following syntax is supported:

- Disable all rules: ``- Enable all rules: ``- Disable one or more rules by name: ``- Enable one or more rules by name: ``

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

For example:

  1. ```markdown
  3. ```

or

  1. ```markdown
  3. ```

These changes apply to the entire file regardless of where the comment is
located. Multiple such comments (if present) are applied top-to-bottom. By
default, content of markdownlint-configure-file is assumed to be JSON, but
[options.configParsers](#optionsconfigparsers) can be used to support
alternate formats.