markdownlint-cli
Command Line Interface for MarkdownLint
Installation
npm install -g markdownlint-cli
On macOS you can install via Homebrew:
brew install markdownlint-cli
Usage
markdownlint --help
Usage: markdownlint [options] <files|directories|globs>
MarkdownLint Command Line Interface
Options:
-V, --version output the version number
-c, --config [configFile] configuration file (JSON, JSONC, JS, or YAML)
-d, --dot include files/folders with a dot (for example `.github`)
-f, --fix fix basic errors (does not work with STDIN)
-i, --ignore [file|directory|glob] file(s) to ignore/exclude (default: [])
-j, --json write issues in json format
-o, --output [outputFile] write issues to file (no console)
-p, --ignore-path [file] path to file with ignore pattern(s)
-q, --quiet do not write issues to STDOUT
-r, --rules [file|directory|glob|package] include custom rule files (default: [])
-s, --stdin read from STDIN (does not work with files)
--enable [rules...] Enable certain rules, e.g. --enable MD013 MD041 --
--disable [rules...] Disable certain rules, e.g. --disable MD013 MD041 --
-h, --help display help for command
Or run using Docker and GitHub Packages:
docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "*.md"
Note Because
--enable
and--disable
are variadic arguments that accept multiple values, it is necessary to end the list by passing--
before the<files|directories|globs>
argument like so:markdownlint --disable MD013 -- README.md
.
Globbing
markdownlint-cli
supports advanced globbing patterns like **/*.md
(more information).
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.
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 from markdownlint
package.
Configuration is stored in JSON, JSONC, YAML, or INI files in the same config format.
A sample configuration file:
{
"default": true,
"MD003": { "style": "atx_closed" },
"MD007": { "indent": 4 },
"no-hard-tabs": false,
"whitespace": false
}
For more examples, see .markdownlint.jsonc, .markdownlint.yaml, or the style folder.
The CLI argument --config
is not required.
If it is not provided, markdownlint-cli
looks for the file .markdownlint.jsonc
/.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.
Note that when relying on the lookup of a file named .markdownlintrc
in the current or parent folders, the only syntaxes accepted are INI and JSON, and the file cannot have an extension.
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
or .cjs
file extension, and must export (via module.exports = ...
) a configuration object of the form shown above.
If your workspace (project) is ESM-only ("type": "module"
set in the root package.json
file), then the configuration file should end with .cjs
file extension.
A JS configuration file may internally require
one or more npm packages as a way of reusing configuration across projects.
--enable
and --disable
override configuration files; if a configuration file disables MD123
and you pass --enable MD123
, it will be enabled.
If a rule is passed to both --enable
and --disable
, it will be disabled.
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 successfully1
: Linting errors2
: Unable to write-o
/--output
output file3
: Unable to load-r
/--rules
custom rule4
: Unexpected error (e.g. malformed config)
Use with pre-commit
To run markdownlint-cli
as part of a pre-commit workflow, add something like the below to the repos
list in the project's .pre-commit-config.yaml
:
- repo: https://github.com/igorshubovych/markdownlint-cli
rev: v0.39.0
hooks:
- id: markdownlint
Depending on the environment this workflow runs in, it may be necessary to override the language version of Node.js used by pre-commit.
Related
- markdownlint - API for this module
- markdownlint-cli2 - Alternate CLI implementation
- glob - Pattern matching implementation
- ignore -
.markdownlintignore
implementation
License
MIT © Igor Shubovych