markdownlint-cli

repository·master·Indexed 22 days ago

https://github.com/igorshubovych/markdownlint-cli

A command-line interface for the markdownlint tool used to lint Markdown files for style and consistency. Version 0.49.1 supports automatic fixing of basic issues, advanced globbing patterns, and custom rule files. It provides flexible configuration via JSON, JSONC, JS, YAML, or TOML files and can be installed via npm, Homebrew, or Docker.

Tokens: 2.2K
Snippets: 8
Records: 14
Agent score: 28%

What's inside markdownlint-cli

Ignore files and directories
master
Exclusions are applied in the following order:
1. Files/directories/globs passed on the command line.
2. Exclusions from the file specified by -p/--ignore-path (if provided) OR the .markdownlintignore file (if present in the current folder).
3. Exclusions from any -i/--ignore options specified on the command line.
.markdownlintignore follows gitignore rules.
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
Use globbing patterns with markdownlint-cli
master
The CLI supports advanced globbing patterns like **/*.md.
Shell Quoting: When using shells like Bash, you should quote your globs to prevent the shell from expanding them before they reach markdownlint-cli. If you don't quote them, the shell might expand --ignore *.md into a list of files, causing the --ignore flag to only apply to the first file in that list.
Examples:
- Windows CMD: markdownlint **/*.md --ignore node_modules
- Linux Bash: markdownlint '**/*.md' --ignore node_modules
```
markdownlint '**/*.md' --ignore node_modules
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
Use markdownlint-cli via Command Line
master
The CLI follows the pattern: markdownlint [options] [files|directories|globs...].
Important Note on Variadic Arguments: Because --enable and --disable accept multiple values, you must use -- to signal the end of the rule list before providing your files or directories.
Example: markdownlint --disable MD013 -- README.md
```
markdownlint --disable MD013 -- README.md
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
Fix markdown issues automatically
master
Use the --fix option to attempt to apply all fixes reported by the active rules.
Warnings:
- This modifies your input files. It is recommended to use source control or create backups first.
- Not all rules provide fix information, so --fix may not address all issues.
- --fix does not work when reading from STDIN.
```
markdownlint --fix README.md
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
Install markdownlint-cli
master
You can install markdownlint-cli globally via npm or via Homebrew on macOS.
npm:
```
npm install -g markdownlint-cli
```
Homebrew (macOS):
```
brew install markdownlint-cli
```
Docker: You can also run it using Docker and GitHub Packages:
```
docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "*.md"
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
Integrate markdownlint-cli with pre-commit
master
To run markdownlint-cli automatically during a pre-commit workflow, add the following to your .pre-commit-config.yaml:
```
- repo: https://github.com/igorshubovych/markdownlint-cli
  rev: v0.49.1
  hooks:
  - id: markdownlint
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
Configure markdownlint-cli
master
Configuration can be defined in JSON, JSONC, JS, YAML, or TOML files.
Automatic Configuration Lookup: If --config is not provided, the CLI looks for:
1. .markdownlint.jsonc, .markdownlint.json, .markdownlint.yaml, or .markdownlint.yml in the current folder.
2. .markdownlintrc in the current or all parent folders (supports only INI and JSON, and must not have an extension).
Manual Configuration via --config:
- JS Files: Must have .js or .cjs extension. If your project is ESM-only ("type": "module" in package.json), use the .cjs extension. JS files must be explicitly provided via --config for security reasons.
- TOML Files: Must be explicitly provided via --config.
- JSON Pointer: Use --configPointer <pointer> to target a specific sub-object within a configuration file (e.g., nesting config inside package.json using /key/subkey).
Rule Overrides: --enable and --disable override settings in your configuration files.
```
{
  "default": true,
  "MD003": { "style": "atx_closed" },
  "MD007": { "indent": 4 },
  "no-hard-tabs": false,
  "whitespace": false
}
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/README.md
How markdownlint-cli handles configuration files
master
The tool looks for configuration in the following order:
1. Global/User Config: Loaded via the rc package (e.g., ~/.markdownlintrc).
2. Project Config: It searches for well-known files in the project root:
  .markdownlint.jsonc
  .markdownlint.json
  .markdownlint.yaml
  .markdownlint.yml
3. Explicit Config: The file provided via the --config flag.
Supported formats include JSON, JSONC (JSON with comments), JavaScript (.js, .cjs, .mjs), YAML, and TOML. If a --configPointer is provided, the tool will use that specific sub-object from the configuration as the active ruleset.
https://github.com/igorshubovych/markdownlint-cli/blob/master/markdownlint.js
Use custom rules with markdownlint-cli
master
You can extend the linter by providing custom rule files or packages using the --rules flag. The tool can resolve local file paths or npm packages.
```
# Load rules from a local directory
markdownlint --rules ./my-custom-rules/ "**/*.md"

# Load rules from an npm package
markdownlint --rules my-markdown-rules-package "**/*.md"
```
https://github.com/igorshubovych/markdownlint-cli/blob/master/markdownlint.js

Reference: markdownlint-cli exit codes

master

The CLI returns the following exit codes:

Code	Meaning
`0`	Linting successful, no errors (warnings possible)
`1`	Linting successful, some errors (warnings possible)
`2`	Unable to write `-o`/`--output` output file
`3`	Unable to load `-r`/`--rules` custom rule
`4`	Unexpected problem (e.g. malformed config)

Reference: markdownlint CLI options

master

The following options are available for the markdownlint command:

Option	Description
`-V, --version`	Output the version number
`-c, --config <configFile>`	Configuration file (JSON, JSONC, JS, YAML, or TOML)
`--configPointer <pointer>`	JSON Pointer to object within configuration file (default: "")
`-d, --dot`	Include files/folders with a dot (e.g., `.github`)
`-f, --fix`	Fix basic issues (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

Understand markdownlint-cli exit codes
master
The CLI uses specific exit codes to indicate the result of the linting process, which is useful for CI/CD pipelines:
Exit Code Meaning
1 Lint errors were found (severity is 'error')
2 Failed to write the output file
3 Failed to load custom rules
4 An unexpected error occurred
https://github.com/igorshubovych/markdownlint-cli/blob/master/markdownlint.js

Exit Code	Meaning
`1`	Lint errors were found (severity is 'error')
`2`	Failed to write the output file
`3`	Failed to load custom rules
`4`	An unexpected error occurred