Overview
markdownlint-cli2 checks Markdown files against a list of rules, each with a code such as MD012, and prints a line for every problem with the file, the line number and the rule name. It reads a configuration file to turn rules on or off, and it can fix many problems with --fix. It needs Node.js.
Background
markdownlint-cli2 is an open-source command-line tool for the markdownlint library, which defines the rules. The tool tested here is markdownlint-cli2 0.24.0 with markdownlint 0.42.0.
Examples
Check a file that has too many blank lines; the lines that name the rule are counted:
printf '# Title\n\n\n\ntext\n' > a.md && { markdownlint-cli2 a.md 2>&1 | grep -c MD012; }
Show the first problem found, which names the file, the line, the rule and what is wrong:
printf '# Title\n\n\n\ntext\n' > a.md && { markdownlint-cli2 a.md 2>&1 | grep -m1 MD012 | cut -d' ' -f1,3; }
Fix what can be fixed automatically with --fix, then check again:
printf '# Title\n\n\n\ntext\n' > a.md && markdownlint-cli2 --fix a.md > /dev/null 2>&1; markdownlint-cli2 a.md > /dev/null 2>&1 && echo clean
Options
--fix
Fix the problems that can be fixed, in place.
--config
Use this configuration file.
Common mistakes
The exit status is 1 when problems are found, so a script with set -e stops. A rule you disagree with should be turned off in .markdownlint-cli2.jsonc or in the file, with a comment such as <!-- markdownlint-disable MD013 -->, and not ignored by habit. The first lines of output name the tool and its version, which changes between versions. --fix rewrites the files: use version control. Globs need quotes, so that the tool and not the shell expands them.
Portability
The rules are the same on every system, and new rules and changed defaults arrive with new versions. The examples were executed on markdownlint-cli2 0.24.0, running on the host's Node.js. The Common examples were executed on markdownlint-cli2 0.24.0 (see the development guide for the exact check).
About upstream markdownlint-cli2
This is the upstream markdownlint-cli2 tool, installed with npm. Its version is the one in your project or the global one.
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.