mdbook-lint

A fast, configurable linter designed for mdBook projects. Works as both an mdBook preprocessor and standalone CLI tool.

📖 Documentation | 🚀 Getting Started

Installation

From Prebuilt Binaries (Recommended)

Download the latest release for your platform from GitHub Releases:

Linux (x86_64): mdbook-lint-linux-x86_64
Linux (musl): mdbook-lint-linux-x86_64-musl (static binary, no dependencies)
Windows: mdbook-lint-windows-x86_64.exe
macOS (Intel): mdbook-lint-macos-x86_64
macOS (Apple Silicon): mdbook-lint-macos-aarch64

Extract and add to your PATH, or use with GitHub Actions (see CI Integration).

From Cargo

cargo install mdbook-lint

Verify the installation:

mdbook-lint --version

Features

✅ Native mdBook integration - Seamless preprocessor integration
✅ 67 linting rules - 54 standard markdown + 13 mdBook-specific rules
✅ Auto-fix support - Automatically fix 13+ common issues
✅ Fast performance - Lint entire books in seconds
✅ Configurable - Disable rules, set custom parameters
✅ Cross-platform - Prebuilt binaries for all major platforms

Usage

mdBook Preprocessor (Primary Use Case)

Add to your book.toml:

[preprocessor.mdbook-lint]

Then run mdbook build as usual. The linter will automatically check all your markdown files and report issues during the build process.

CLI (Standalone)

# Lint files
mdbook-lint lint README.md src/*.md

# Auto-fix violations where possible
mdbook-lint lint --fix src/*.md

# Preview what would be fixed
mdbook-lint lint --fix --dry-run src/*.md

# Show available rules
mdbook-lint rules

Configuration

Create a .mdbook-lint.toml file:

fail-on-warnings = true
disabled-rules = ["MD013"]  # Disable line length rule

# Configure specific rules
[rules.MD007]
indent = 4  # Use 4 spaces for list indentation

[rules.MD009] 
br_spaces = 2  # Allow 2 trailing spaces for line breaks

See the example configuration for all available options.

Rules

54 standard rules (MD001-MD059) - All the usual markdown linting
13 mdBook rules (MDBOOK001-012, MDBOOK025) - mdBook-specific checks

Run mdbook-lint rules --detailed to see all available rules.

CI Integration

GitHub Actions

name: Lint Documentation
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Download mdbook-lint
        run: |
          curl -sSL https://github.com/joshrotenberg/mdbook-lint/releases/latest/download/mdbook-lint-linux-x86_64 -o mdbook-lint
          chmod +x mdbook-lint
      
      - name: Lint markdown files
        run: ./mdbook-lint lint --fail-on-warnings docs/

Contributing

Contributions are welcome! See our Contributing Guide for complete information.

License

MIT OR Apache-2.0

mdbook-lint 0.11.3