CLI Usage

This page documents the command-line interface for mdbook-lint.

Basic Commands

lint

Lint markdown files and directories.

mdbook-lint lint [OPTIONS] [PATHS]...

rules

List available linting rules.

mdbook-lint rules [OPTIONS]

help

Show help information.

mdbook-lint help [COMMAND]

Options

Global Options

• -h, --help: Print help information
• -V, --version: Print version information
• -v, --verbose: Enable verbose output
• -q, --quiet: Suppress non-error output

Lint Options

• --config <FILE>: Use specific configuration file
• --fail-on-warnings: Exit with error code on warnings
• --disable <RULES>: Disable specific rules (comma-separated)
• --enable <RULES>: Enable only specific rules (comma-separated)
• --fix: Automatically fix violations where possible
• --fix-unsafe: Apply all fixes, including potentially unsafe ones
• --dry-run: Show what would be fixed without applying changes (requires --fix or --fix-unsafe)
• --no-backup: Skip creating backup files when applying fixes
• --output <FORMAT>: Output format (default, json, github)
• --color <WHEN>: Control colored output (auto, always, never)

Rules Options

• --detailed: Show detailed rule descriptions
• --enabled: Show only enabled rules
• --format <FORMAT>: Output format (text, json)

Output Format

By default, mdbook-lint displays violations in a cargo/rustc-style format with colors:

error[MD001]: Expected heading level 2 but got level 3
  --> src/chapter.md:15:1
     |
  15 | ### Skipped heading level
     | ^^^ heading-increment

warning[MD009]: Trailing spaces detected
  --> src/intro.md:8:42
     |
   8 | This line has trailing spaces   
     |                                  ^ no-trailing-spaces

Found: 1 error(s), 1 warning(s)

Output Formats

• default: Colored, human-readable format (shown above)
• json: Machine-readable JSON output
• github: GitHub Actions annotation format

Controlling Colors

Use --color to control colored output:

# Auto-detect (default) - colors when terminal supports it
mdbook-lint lint docs/

# Always use colors (useful for CI with color support)
mdbook-lint lint --color always docs/

# Never use colors (useful for piping to files)
mdbook-lint lint --color never docs/ > report.txt

Examples

# Lint current directory
mdbook-lint lint .

# Lint specific files
mdbook-lint lint README.md src/chapter1.md

# Lint with custom config
mdbook-lint lint --config custom-lint.toml src/

# Auto-fix violations where possible
mdbook-lint lint --fix docs/

# Preview fixes without applying them
mdbook-lint lint --fix --dry-run docs/

# Apply all fixes including potentially unsafe ones
mdbook-lint lint --fix-unsafe docs/

# Fix without creating backup files
mdbook-lint lint --fix --no-backup docs/

# Show all rules with descriptions
mdbook-lint rules --detailed

# Lint and fail on warnings
mdbook-lint lint --fail-on-warnings docs/

Exit Codes

• 0: Success (no errors)
• 1: Linting errors found
• 2: Invalid arguments or configuration

Next Steps

• Learn about mdBook Integration
• See Configuration Reference for all options