markdownlint-cli

markdownlint-cli wraps the markdownlint rule engine in a standalone command-line tool so teams can lint Markdown files in CI, pre-commit hooks, and local editors without writing any Node.js integration code. It walks files, directories, or glob patterns, applies a configurable rule set, and reports violations with file, line, and rule-name context, or writes them as JSON for tooling to consume.

Configuration can come from JSON, JSONC, YAML, or JS files, with sensible defaults if none are present, and rules can be toggled per-invocation with —enable/—disable flags. The —fix flag applies any auto-fixable violations in place, and a Docker image plus a pre-commit hook definition make it easy to drop into existing pipelines with no local Node.js install required.

What You Get

• A single-binary CLI (markdownlint) installable via npm, Homebrew, or Docker
• Support for JSON, JSONC, YAML, TOML, and JS configuration files with automatic discovery of .markdownlint.* files
• Glob, directory, and multi-file input handling with .markdownlintignore and --ignore exclusion support
• An --fix flag that rewrites files in place to resolve auto-fixable rule violations
• JSON output mode (--json) for machine-readable integration with other tooling
• Support for loading custom rule files/packages via --rules

Common Use Cases

• Enforcing Markdown style consistency across a documentation repository in CI
• Running as a pre-commit hook to catch formatting issues before they’re committed
• Auto-fixing common Markdown issues (trailing whitespace, heading style, list indentation) with --fix
• Linting README and docs files in a Docker-based CI pipeline without a Node.js toolchain
• Integrating custom project-specific Markdown rules via the --rules option

Under The Hood

Architecture The entire CLI lives in a single executable script, markdownlint.js, which builds a Commander.js argument parser, resolves an input file list via glob/directory/file resolution helpers, loads configuration from .markdownlint.* files or an explicit --config path via a small dispatch table of JSON/JSONC/YAML/TOML parsers, and delegates the actual rule evaluation to the separate markdownlint package’s synchronous lint/applyFixes API. There is no internal module boundary beyond this one file, which is appropriate given the tool’s narrow scope: parse args, resolve files, load config, call the linting engine, print results.

Tech Stack Built on Node.js (>=22, ESM-only, "type": "module") using commander for CLI argument parsing, tinyglobby and minimatch for glob resolution, ignore for .markdownlintignore handling, and run-con plus js-yaml/jsonc-parser/smol-toml for multi-format configuration loading. The actual linting rules and fix logic come from the separate markdownlint npm package, which this CLI wraps rather than reimplements. Docker packaging publishes a ghcr.io image alongside npm/Homebrew distribution.

Code Quality Tests are written with the ava test runner and cover CLI flag behavior, config-file discovery/precedence, custom rules, --fix output, and JSON output formatting against fixture Markdown files in test/. Linting is enforced via xo (an ESLint preset) as part of the precommit script, and CI runs the full test-and-lint suite across Node 22/24/26 on Ubuntu, macOS, and Windows, giving strong cross-platform confidence for a tool whose job is file-path and glob handling that behaves differently per OS.

What Makes It Unique Rather than building its own Markdown rule engine, markdownlint-cli focuses entirely on being an excellent CLI wrapper: multi-format configuration (JSON/JSONC/YAML/TOML/JS) with JSON Pointer sub-object selection (--configPointer), pluggable custom rule loading by package name or path, and first-class --fix support that rewrites files safely one at a time. This narrow, well-tested scope is what makes it the de facto standard CLI for the underlying markdownlint rule engine rather than a competing implementation.