rumdl - A high-performance Markdown linter, written in Rust

A modern Markdown linter and formatter, built for speed with Rust

| Docs | Rules | Configuration |

Table of Contents

• rumdl - A high-performance Markdown linter, written in Rust
  • A modern Markdown linter and formatter, built for speed with Rust
  • Table of Contents
  • Quick Start
  • Overview
  • Installation
    • Using Cargo (Rust)
    • Using pip (Python)
    • Download binary
  • Usage
  • Pre-commit Integration
  • Rules
  • Command-line Interface
    • Commands
    • Options (for check)
    • Example Help Output
  • Configuration
    • Configuration File Example
    • Initializing Configuration
    • Configuration in pyproject.toml
  • Output Style
    • Output Format
  • Development
    • Prerequisites
    • Building
    • Testing
  • License

Quick Start

# Install using Cargo
cargo install rumdl

# Lint Markdown files in the current directory
rumdl check .

# Automatically fix issues
rumdl check --fix .

# Create a default configuration file
rumdl init

Overview

rumdl is a high-performance Markdown linter and fixer that helps ensure consistency and best practices in your Markdown files. It offers:

• ⚡️ Built for speed with Rust
• 🔍 50+ lint rules covering common Markdown issues
• 🛠️ Automatic fixing with --fix for most rules
• 📦 Zero dependencies - single binary with no runtime requirements
• 🔧 Highly configurable with TOML-based config files
• 🌐 Multiple installation options - Rust, Python, standalone binaries
• 🐍 Installable via pip for Python users
• 📏 Modern CLI with detailed error reporting
• 🔄 CI/CD friendly with non-zero exit code on errors

Installation

Choose the installation method that works best for you:

Using Cargo (Rust)

cargo install rumdl

Using pip (Python)

pip install rumdl

Download binary

# Linux/macOS
curl -LsSf https://github.com/rvben/rumdl/releases/latest/download/rumdl-linux-x86_64.tar.gz | tar xzf - -C /usr/local/bin

# Windows PowerShell
Invoke-WebRequest -Uri "https://github.com/rvben/rumdl/releases/latest/download/rumdl-windows-x86_64.zip" -OutFile "rumdl.zip"
Expand-Archive -Path "rumdl.zip" -DestinationPath "$env:USERPROFILE\.rumdl"

Usage

Getting started with rumdl is simple:

# Lint a single file
rumdl check README.md

# Lint all Markdown files in current directory and subdirectories
rumdl check .

# Automatically fix issues
rumdl check --fix README.md

# Create a default configuration file
rumdl init

Common usage examples:

# Lint with custom configuration
rumdl check --config my-config.toml docs/

# Disable specific rules
rumdl check --disable MD013,MD033 README.md

# Enable only specific rules
rumdl check --enable MD001,MD003 README.md

# Exclude specific files/directories
rumdl check --exclude "node_modules,dist" .

# Include only specific files/directories
rumdl check --include "docs/*.md,README.md" .

# Combine include and exclude patterns
rumdl check --include "docs/**/*.md" --exclude "docs/temp,docs/drafts" .

# Ignore gitignore rules
rumdl check --no-respect-gitignore .

Pre-commit Integration

You can use rumdl as a pre-commit hook to check and fix your Markdown files.

The recommended way is to use the official pre-commit hook repository:

rumdl-pre-commit repository

Add the following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/rvben/rumdl-pre-commit
    rev: v0.0.45  # Use the latest release tag
    hooks:
      - id: rumdl
        # To only check (default):
        # args: []
        # To automatically fix issues:
        # args: [--fix]

• By default, the hook will only check for issues.
• To automatically fix issues, add args: [--fix] to the hook configuration.

When you run pre-commit install or pre-commit run, pre-commit will automatically install rumdl in an isolated Python environment using pip. You do not need to install rumdl manually.

Rules

rumdl implements over 50 lint rules for Markdown files. Here are some key rule categories:

For a complete list of rules and their descriptions, see our documentation or run:

rumdl --list-rules

Command-line Interface

rumdl <command> [options] [file or directory...]

Commands

• check: Lint Markdown files and print warnings/errors (main subcommand)
• init: Create a default .rumdl.toml configuration file in the current directory

Options (for check)

• -c, --config <file>: Use custom configuration file
• --fix: Automatically fix issues where possible
• -l, --list-rules: List all available rules
• -d, --disable <rules>: Disable specific rules (comma-separated)
• -e, --enable <rules>: Enable only specific rules (comma-separated)
• --exclude <patterns>: Exclude specific files or directories (comma-separated glob patterns)
• --include <patterns>: Include only specific files or directories (comma-separated glob patterns)
• --respect-gitignore: Respect .gitignore files when scanning directories (default: true)
• --no-respect-gitignore: Don't respect .gitignore files (same as --ignore-gitignore)
• -v, --verbose: Show detailed output
• --profile: Show profiling information
• -q, --quiet: Suppress all output except errors

Example Help Output

rumdl --help

Usage: rumdl <COMMAND> [OPTIONS] [PATHS...]

Commands:
  check    Lint Markdown files and print warnings/errors
  init     Create a default configuration file

Options (for 'check' subcommand):
  --fix                  Automatically fix fixable issues
  --rules <RULES>        Comma-separated list of rules to enable
  --config <FILE>        Path to configuration file
  --format <FORMAT>      Output format (default: text)
  --help                 Print help information
  --version              Print version information

If no command is given, 'check' is assumed (deprecated).

Configuration

rumdl can be configured in several ways:

1. Using a .rumdl.toml file in your project directory
2. Using the [tool.rumdl] section in your project's pyproject.toml file (for Python projects)
3. Using command-line arguments

Configuration File Example

Here's an example .rumdl.toml configuration file:

# Global settings
line-length = 100
exclude = ["node_modules", "build", "dist"]
respect-gitignore = true

# Disable specific rules
disabled-rules = ["MD013", "MD033"]

# Configure individual rules
[MD007]
indent = 2

[MD013]
line-length = 100
code-blocks = false
tables = false

[MD025]
level = 1
front-matter-title = "title"

[MD044]
names = ["rumdl", "Markdown", "GitHub"]

[MD048]
code-fence-style = "backtick"

Initializing Configuration

To create a configuration file, use the init command:

# Create a .rumdl.toml file (for any project)
rumdl init

# Create or update a pyproject.toml file with rumdl configuration (for Python projects)
rumdl init --pyproject

Configuration in pyproject.toml

For Python projects, you can include rumdl configuration in your pyproject.toml file, keeping all project configuration in one place. Example:

[tool.rumdl]
# Global options at root level
line-length = 100
disable = ["MD033"]
include = ["docs/*.md", "README.md"]
exclude = [".git", "node_modules"]
ignore-gitignore = false

# Rule-specific configuration
[tool.rumdl.MD013]
code_blocks = false
tables = false

[tool.rumdl.MD044]
names = ["rumdl", "Markdown", "GitHub"]

Both kebab-case (line-length, ignore-gitignore) and snake_case (line_length, ignore_gitignore) formats are supported for compatibility with different Python tooling conventions.

Output Style

rumdl produces clean, colorized output similar to modern linting tools:

README.md:12:1: [MD022] Headings should be surrounded by blank lines [*]
README.md:24:5: [MD037] Spaces inside emphasis markers: "* incorrect *" [*]
README.md:31:76: [MD013] Line length exceeds 80 characters
README.md:42:3: [MD010] Hard tabs found, use spaces instead [*]

When running with --fix, rumdl shows which issues were fixed:

README.md:12:1: [MD022] Headings should be surrounded by blank lines [fixed]
README.md:24:5: [MD037] Spaces inside emphasis markers: "* incorrect *" [fixed]
README.md:42:3: [MD010] Hard tabs found, use spaces instead [fixed]

Fixed 3 issues in 1 file

For a more detailed view, use the --verbose option:

✓ No issues found in CONTRIBUTING.md
README.md:12:1: [MD022] Headings should be surrounded by blank lines [*]
README.md:24:5: [MD037] Spaces inside emphasis markers: "* incorrect *" [*]
README.md:42:3: [MD010] Hard tabs found, use spaces instead [*]

Found 3 issues in 1 file (2 files checked)
Run with `--fix` to automatically fix issues

Output Format

rumdl uses a consistent output format for all issues:

{file}:{line}:{column}: [{rule*id}] {message} [{fix*indicator}]

The output is colorized by default:

• Filenames appear in blue and underlined
• Line and column numbers appear in cyan
• Rule IDs appear in yellow
• Error messages appear in white
• Fixable issues are marked with [*] in green
• Fixed issues are marked with [fixed] in green

Development

Prerequisites

• Rust 1.70 or higher
• Make (for development commands)

Building

make build

Testing

make test

License

rumdl is licensed under the MIT License. See the LICENSE file for details.