mdcheck

A linter and validator for Markdown files that enforces the CommonMark specification.
Think cargo check, but for Markdown.

Features

✅ Validates CommonMark compliance
✅ Detects undefined link references
✅ Checks list and indentation consistency
✅ Enforces header level progression
✅ Detects bare URLs
✅ Skips validation inside code blocks
✅ Recursive directory scanning
✅ Multiple output formats (human-readable, JSON)
✅ Unclosed element detection

Installation

From crates.io

cargo install mdcheck

Build locally

git clone https://github.com/fibnas/mdcheck
cd mdcheck
cargo run --release

Usage

Run mdcheck on Markdown files or directories.

Check specific files

mdcheck file1.md file2.md

Check all Markdown files in a directory

mdcheck docs/

Recursively check all Markdown files

mdcheck -r project/

Output in JSON format

mdcheck -o json file.md

Strict mode (treat warnings as errors)

mdcheck -s file.md

Ignore warnings

mdcheck -w file.md

Exit Codes

Code	Meaning
0	Success — no errors (and no warnings in strict mode)
1	Failure — errors found, or warnings in strict mode

Example Output

document.md:
  error 3: Undefined link reference '[missing]'
  warning 7: Bare URL detected (consider using link syntax)
  warning 12: Inconsistent indentation (prefer 2 or 4 spaces)

Summary: 1 error, 2 warnings in 1 file

Checks Performed

Errors

Undefined link references
Unclosed Markdown elements
File read errors

Warnings

Bare URLs without link syntax
Inconsistent indentation (not 2 or 4 spaces)
Inconsistent list indentation
Header level jumps (e.g. from H1 to H3)

Command-Line Help

$ mdcheck --help
mdcheck 0.1.1
Linter and validator for Markdown files that enforces CommonMark compliance.

USAGE:
    mdcheck [OPTIONS] <PATHS>...

ARGS:
    <PATHS>...    One or more Markdown files or directories to check

OPTIONS:
    -r, --recursive       Recursively check all Markdown files in subdirectories
    -o, --output <FORMAT>  Output format: "human" (default) or "json"
    -s, --strict          Treat warnings as errors (non-zero exit)
    -w, --ignore-warnings Ignore warnings, only show errors
    -q, --quiet           Suppress non-error output
    -h, --help            Print this help information
    -V, --version         Show version information

EXAMPLES:
    mdcheck README.md
    mdcheck -r docs/
    mdcheck -o json -s src/docs/
    mdcheck -w file1.md file2.md

EXIT CODES:
    0  No issues found
    1  Errors or warnings (in strict mode)

More info: https://github.com/fibnas/mdcheck
License: MIT

Configuration

Currently configured via command-line flags.
Future versions may support config files for custom rule sets.

Contributing

Pull requests are welcome!
Fork, tinker, and open an issue or PR if you’ve got ideas or improvements.

License

MIT

mdcheck 0.1.0