UNPKG

6.31 kBMarkdownView Raw
1# markdownlint-cli
2
3[![GitHub Actions Build Status][actions-badge]][actions-url]
4
5> Command Line Interface for [MarkdownLint][markdownlint]
6
7## Installation
8
9```bash
10npm install -g markdownlint-cli
11```
12
13On macOS you can install via [Homebrew](https://brew.sh/):
14
15```bash
16brew install markdownlint-cli
17```
18
19## Usage
20
21```bash
22markdownlint --help
23
24 Usage: markdownlint [options] <files|directories|globs>
25
26 MarkdownLint Command Line Interface
27
28 Options:
29
30 -h, --help output usage information
31 -V, --version output the version number
32 -c, --config [configFile] configuration file (JSON, JSONC, JS, or YAML)
33 -d, --dot include files/folders with a dot (for example `.github`)
34 -f, --fix fix basic errors (does not work with STDIN)
35 -i, --ignore [file|directory|glob] file(s) to ignore/exclude
36 -o, --output [outputFile] write issues to file (no console)
37 -p, --ignore-path [file] path to file with ignore pattern(s)
38 -r, --rules [file|directory|glob|package] custom rule files
39 -s, --stdin read from STDIN (does not work with files)
40```
41
42### Globbing
43
44`markdownlint-cli` supports advanced globbing patterns like `**/*.md` ([more information][globprimer]).
45With shells like Bash, it may be necessary to quote globs so they are not interpreted by the shell.
46For 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).
47Quoting the glob like `--ignore '*.md'` passes it through unexpanded and ignores the set of files.
48
49#### Globbing examples
50
51To lint all Markdown files in a Node.js project (excluding dependencies), the following commands might be used:
52
53Windows CMD: `markdownlint **/*.md --ignore node_modules`
54
55Linux Bash: `markdownlint '**/*.md' --ignore node_modules`
56
57### Ignoring files
58
59If present in the current folder, a `.markdownlintignore` file will be used to ignore files and/or directories according to the rules for [gitignore][gitignore].
60If the `-p`/`--ignore-path` option is present, the specified file will be used instead of `.markdownlintignore`.
61
62The order of operations is:
63
64- Enumerate files/directories/globs passed on the command line
65- Apply exclusions from `-p`/`--ignore-path` (if specified) or `.markdownlintignore` (if present)
66- Apply exclusions from any `-i`/`--ignore` option(s) that are specified
67
68### Fixing errors
69
70When the `--fix` option is specified, `markdownlint-cli` tries to apply all fixes reported by the active rules and reports any errors that remain.
71Because 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.
72
73> 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.
74
75## Configuration
76
77`markdownlint-cli` reuses [the rules][rules] from `markdownlint` package.
78
79Configuration is stored in JSON, JSONC, YAML, or INI files in the same [config format][config].
80
81A sample configuration file:
82
83```json
84{
85 "default": true,
86 "MD003": { "style": "atx_closed" },
87 "MD007": { "indent": 4 },
88 "no-hard-tabs": false,
89 "whitespace": false
90}
91```
92
93For more examples, see [.markdownlint.jsonc][markdownlint-jsonc], [.markdownlint.yaml][markdownlint-yaml], or the [style folder][style-folder].
94
95The CLI argument `--config` is not required.
96If 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.
97The algorithm is described in detail on the [`rc` package page][rc-standards].
98If the `--config` argument is provided, the file must be valid JSON, JSONC, JS, or YAML.
99JS configuration files contain JavaScript code, must have the `.js` extension, and must export (via `module.exports = ...`) a configuration object of the form shown above.
100A JS configuration file may internally `require` one or more npm packages as a way of reusing configuration across projects.
101
102> JS configuration files must be provided via the `--config` argument; they are not automatically loaded because running untrusted code is a security concern.
103
104## Exit codes
105
106`markdownlint-cli` returns one of the following exit codes:
107
108- `0`: Program ran successfully
109- `1`: Linting errors / bad parameter
110- `2`: Unable to write `-o`/`--output` output file
111- `3`: Unable to load `-r`/`--rules` custom rule
112
113## Use with pre-commit
114
115To run `markdownlint-cli` as part of a [pre-commit](https://pre-commit.com/) workflow, add something like the below to the `repos` list in the project's `.pre-commit-config.yaml`:
116
117```yaml
118- repo: https://github.com/igorshubovych/markdownlint-cli
119 rev: v0.27.1
120 hooks:
121 - id: markdownlint
122```
123
124## Related
125
126- [markdownlint][markdownlint] - API for this module
127- [glob][glob] - Pattern matching implementation
128- [ignore][ignore] - `.markdownlintignore` implementation
129
130## License
131
132MIT © Igor Shubovych
133
134[actions-badge]: https://github.com/igorshubovych/markdownlint-cli/workflows/CI/badge.svg?branch=master
135[actions-url]: https://github.com/igorshubovych/markdownlint-cli/actions?query=workflow%3ACI
136[markdownlint]: https://github.com/DavidAnson/markdownlint
137[markdownlint-jsonc]: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.jsonc
138[markdownlint-yaml]: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
139[rules]: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
140[config]: https://github.com/DavidAnson/markdownlint#optionsconfig
141[style-folder]: https://github.com/DavidAnson/markdownlint/tree/main/style
142[rc-standards]: https://www.npmjs.com/package/rc#standards
143[glob]: https://github.com/isaacs/node-glob
144[globprimer]: https://github.com/isaacs/node-glob/blob/master/README.md#glob-primer
145[ignore]: https://github.com/kaelzhang/node-ignore
146[gitignore]: https://git-scm.com/docs/gitignore