markdownlint-cli2

A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the markdownlint library

Install

As a global CLI:

npm install markdownlint-cli2 --global

As a development dependency of the current package:

npm install markdownlint-cli2 --save-dev

Or as a Docker container image:

docker pull davidanson/markdownlint-cli2

Overview

markdownlint is a library for linting Markdown/ CommonMark files on Node.js using the markdown-it parser.
markdownlint-cli is a traditional command-line interface for markdownlint.
markdownlint-cli2 is a slightly unconventional command-line interface for markdownlint.
markdownlint-cli2 is configuration-based and prioritizes speed and simplicity.
markdownlint-cli2 supports all the features of markdownlint-cli (sometimes a little differently).
vscode-markdownlint is a markdownlint extension for the Visual Studio Code editor.
markdownlint-cli2 is designed to work well in conjunction with vscode-markdownlint.
More about the motivation for markdownlint-cli2.

Use

Command Line

markdownlint-cli2 vX.Y.Z (markdownlint vX.Y.Z)
https://github.com/DavidAnson/markdownlint-cli2

Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN]
        markdownlint-cli2-fix glob0 [glob1] [...] [globN]
        markdownlint-cli2-config config-file glob0 [glob1] [...] [globN]

Glob expressions (from the globby library):
- * matches any number of characters, but not /
- ? matches a single character, but not /
- ** matches any number of characters, including /
- {} allows for a comma-separated list of "or" expressions
- ! or # at the beginning of a pattern negate the match
- : at the beginning identifies a literal file path

Dot-only glob:
- The command "markdownlint-cli2 ." would lint every file in the current directory tree which is probably not intended
- Instead, it is mapped to "markdownlint-cli2 *.{md,markdown}" which lints all Markdown files in the current directory
- To lint every file in the current directory tree, the command "markdownlint-cli2 **" can be used instead

Configuration via:
- .markdownlint-cli2.jsonc
- .markdownlint-cli2.yaml
- .markdownlint-cli2.cjs or .markdownlint-cli2.mjs
- .markdownlint.jsonc or .markdownlint.json
- .markdownlint.yaml or .markdownlint.yml
- .markdownlint.cjs or .markdownlint.mjs

Cross-platform compatibility:
- UNIX and Windows shells expand globs according to different rules; quoting arguments is recommended
- Some Windows shells don't handle single-quoted (') arguments well; double-quote (") is recommended
- Shells that expand globs do not support negated patterns (!node_modules); quoting is required here
- Some UNIX shells parse exclamation (!) in double-quotes; hashtag (#) is recommended in these cases
- The path separator is forward slash (/) on all platforms; backslash (\) is automatically converted

The most compatible syntax for cross-platform support:
$ markdownlint-cli2 "**/*.md" "#node_modules"

For scenarios where it is preferable to specify glob expressions in a configuration file, the globs property of .markdownlint-cli2.jsonc, .yaml, .cjs, or .mjs may be used instead of (or in addition to) passing glob0 ... globN on the command-line.

As shown above, a typical command-line for markdownlint-cli2 looks something like:

markdownlint-cli2 "**/*.md" "#node_modules"

Because sharing the same configuration between "normal" and "fix" modes is common, the following command defaults the fix property (see below) to true:

markdownlint-cli2-fix "**/*.md" "#node_modules"

Other than the default behavior of the fix property (which can be overridden), these two commands behave identically.

In cases where it is not convenient to store a configuration file in the root of a project, the markdownlint-cli2-config command can be used. This command accepts a path to any supported configuration file as its first argument:

markdownlint-cli2-config "config/.markdownlint-cli2.jsonc" "**/*.md" "#node_modules"

The configuration file name must be (or end with) one of the supported types above. For example, .markdownlint.json or example.markdownlint-cli2.jsonc. The specified configuration file will be loaded, parsed, and applied as a base configuration for the current directory - which will then be handled normally. Otherwise, this command behaves identically to markdownlint-cli2.

Container Image

A container image davidanson/markdownlint-cli2 can also be used (e.g., as part of a CI pipeline):

docker run -v $PWD:/workdir davidanson/markdownlint-cli2:0.5.1 "**/*.md" "#node_modules"

Notes:

As when using the command line, glob patterns are passed as arguments.
This image is built on the official Node.js Docker image. Per security best practices, the default user node runs with restricted permissions. If it is necessary to run as root, pass the -u root option when invoking docker.
By default, markdownlint-cli2 will execute within the /workdir directory inside the container. So, as shown above, bind mount the project's directory there.
- A custom working directory can be specified with Docker's -w flag:
```
docker run -w /myfolder -v $PWD:/myfolder davidanson/markdownlint-cli2:0.5.1 "**/*.md" "#node_modules"
```

To invoke the markdownlint-cli2-config or markdownlint-cli2-fix commands instead, use Docker's --entrypoint flag:

docker run -v $PWD:/workdir --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2:0.5.1 "**/*.md" "#node_modules"

Exit Codes

0: Linting was successful and there were no errors
1: Linting was successful and there were errors
2: Linting was not completed due to a runtime issue

Rule List

See the Rules / Aliases and Tags sections of the markdownlint documentation.

Glob expressions

Globbing is performed by the globby library; refer to that documentation for more information and examples.

Configuration

See the Configuration section of the markdownlint documentation for information about the inline comment syntax for enabling and disabling rules with HTML comments.
In general, glob expressions match files under the current directory and the configuration for that directory applies to the entire tree.
- When glob expressions match files not under the current directory, configuration for the current directory is applied to the closest common parent directory.