mdbook-lint

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

Documentation | Getting Started

What is mdBook?

mdBook is a command-line tool for creating books from Markdown files. It's widely used in the Rust ecosystem for documentation, including The Rust Programming Language book, and is popular for technical documentation projects of all kinds. mdBook renders Markdown into a clean, searchable HTML book format with navigation, search, and syntax highlighting.

mdbook-lint helps ensure your mdBook documentation maintains consistent quality by catching common issues before they reach readers.

Installation

Homebrew (macOS/Linux)

brew tap joshrotenberg/brew
brew install mdbook-lint

From Cargo

cargo install mdbook-lint

By default, this includes all rule sets (standard, mdBook, and content rules). To install without specific rule sets:

# Without content rules (CONTENT001-011)
cargo install mdbook-lint --no-default-features --features standard,mdbook,lsp

# Only standard markdown rules
cargo install mdbook-lint --no-default-features --features standard,lsp

From Prebuilt Binaries

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).

Docker

# Pull from GitHub Container Registry
docker pull ghcr.io/joshrotenberg/mdbook-lint:latest

# Lint files in current directory
docker run --rm -v $(pwd):/workspace ghcr.io/joshrotenberg/mdbook-lint lint .

# Show available rules
docker run --rm ghcr.io/joshrotenberg/mdbook-lint rules

# Use a specific version
docker run --rm -v $(pwd):/workspace ghcr.io/joshrotenberg/mdbook-lint:0.14.2 lint .

Available for linux/amd64 and linux/arm64.

Verify Installation

mdbook-lint --version

Features

• Native mdBook integration - Seamless preprocessor integration
• 100 linting rules - 55 standard markdown + 18 mdBook-specific + 17 ADR + 10 content rules
• Auto-fix support - Automatically fix common issues with 41 rules
• ADR validation - Validate Architecture Decision Records (Nygard and MADR 4.0)
• 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.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 (using the fix subcommand)
mdbook-lint fix src/*.md

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

# Alternative: use lint with --fix flag
mdbook-lint lint --fix src/*.md

# Show available rules
mdbook-lint rules

Output uses cargo-style formatting with colors:

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

Configuration

Create a .mdbook-lint.toml file (also supports YAML/JSON):

# Disable rules that don't fit your project
disabled-rules = ["MD013", "MD033"]

# Configure specific rules
[MD007]
indent = 4

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

[MD003]
style = "atx"  # Use # style headings

Generate a configuration file with all options documented:

mdbook-lint init --include-all

Configuration examples:

• example-mdbook-lint.toml - Comprehensive reference with all 83 rules documented
• docs/.mdbook-lint.toml - Real-world example used by this project's documentation

Rules

• 55 standard rules (MD001-MD060) - All the usual markdown linting
• 18 mdBook rules (MDBOOK001-MDBOOK025) - mdBook-specific checks
• 17 ADR rules (ADR001-ADR017) - Architecture Decision Record validation (Nygard and MADR 4.0)
• 10 content rules (CONTENT001-CONTENT011) - Content quality checks including TODO detection, placeholder text, terminology consistency, link quality, and more

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/

Compatibility

mdbook-lint supports mdBook versions 0.4.x and 0.5.x. The tool automatically detects and handles differences in mdBook's JSON protocol between versions, so it works seamlessly regardless of which mdBook version you have installed.

For detailed compatibility information, see the Compatibility Guide.

Contributing

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

Acknowledgments

mdbook-lint builds on the excellent work of:

• markdownlint - The original Node.js markdown linter that defined the standard rule set (MD001-MD059)
• rumdl - A fast Rust markdown linter that inspired our implementation approach

We aim to be compatible with markdownlint's rule definitions while adding mdBook-specific functionality.

License

MIT OR Apache-2.0