markdownlint-cli

2021-9-16 大约 3 分钟

# markdownlint-cli

Command Line Interface for MarkdownLint (opens new window)

Github address is https://github.com/igorshubovych/markdownlint-cli (opens new window)

# Installation

npm install -g markdownlint-cli

# Usage

markdownlint --help

  Usage: markdownlint [options] <files|directories|globs>

  MarkdownLint Command Line Interface

  Options:

    -h, --help                                  output usage information
    -V, --version                               output the version number
    -f, --fix                                   fix basic errors (does not work with STDIN)
    -s, --stdin                                 read from STDIN (does not work with files)
    -o, --output [outputFile]                   write issues to file (no console)
    -c, --config [configFile]                   configuration file (JSON, JSONC, JS, or YAML)
    -i, --ignore [file|directory|glob]          file(s) to ignore/exclude
    -p, --ignore-path [file]                    path to file with ignore pattern(s)
    -r, --rules  [file|directory|glob|package]  custom rule files

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Globbing

markdownlint-cli supports advanced globbing patterns like **/*.md (more information (opens new window)). With shells like Bash, it may be necessary to quote globs so they are not interpreted by the shell. For example, --ignore *.md would be expanded by Bash to --ignore a.md b.md ... before invoking markdownlint-cli, causing it to ignore only the first file because --ignore takes a single parameter (though it can be used multiple times). Quoting the glob like --ignore '*.md' passes it through unexpanded and ignores the set of files.

# Globbing examples

To lint all Markdown files in a Node.js project (excluding dependencies), the following commands might be used:

Windows CMD: markdownlint **/*.md --ignore node_modules

Linux Bash: markdownlint '**/*.md' --ignore node_modules

# Ignoring files

If present in the current folder, a .markdownlintignore file will be used to ignore files and/or directories according to the rules for gitignore (opens new window). If the -p/--ignore-path option is present, the specified file will be used instead of .markdownlintignore.

The order of operations is:

Enumerate files/directories/globs passed on the command line
Apply exclusions from -p/--ignore-path (if specified) or .markdownlintignore (if present)
Apply exclusions from any -i/--ignore option(s) that are specified

# Fixing errors

When the --fix option is specified, markdownlint-cli tries to apply all fixes reported by the active rules and reports any errors that remain. Because this option makes changes to the input files, it is good to make a backup first or work with files under source control so any unwanted changes can be undone.

Because not all rules include fix information when reporting errors, fixes may overlap, and not all errors are fixable, --fix will not usually address all errors.

# Configuration

markdownlint-cli reuses the rules (opens new window) from markdownlint package.

Configuration is stored in JSON, JSONC, YAML, or INI files in the same config format (opens new window).

The example of configuration file:

{
  "default": true,
  "MD003": { "style": "atx_closed" },
  "MD007": { "indent": 4 },
  "no-hard-tabs": false,
  "whitespace": false
}

1
2
3
4
5
6
7

See test configuration file (opens new window) or style folder (opens new window) for more examples.

The CLI argument --config is not required. If it is not provided, markdownlint-cli looks for the file .markdownlint.json/.markdownlint.yaml/.markdownlint.yml in current folder, or for the file .markdownlintrc in the current or all parent folders. The algorithm is described in detail on the rc package page (opens new window). If the --config argument is provided, the file must be valid JSON, JSONC, JS, or YAML. JS configuration files contain JavaScript code, must have the .js extension, and must export (via module.exports = ...) a configuration object of the form shown above. A JS configuration file may internally require one or more npm packages as a way of reusing configuration across projects.

JS configuration files must be provided via the --config argument; they are not automatically loaded because running untrusted code is a security concern.

# Exit codes

markdownlint-cli returns one of the following exit codes:

0: Program ran successfully
1: Linting errors / bad parameter
2: Unable to write -o/--output output file
3: Unable to load -r/--rules custom rule

markdownlint (opens new window) - API for this module
glob (opens new window) - Pattern matching implementation
ignore (opens new window) - .markdownlintignore implementation

# License

argparse Rules