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

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
    • Usage Examples
  • Configuration
    • Configuration File Example
    • Initializing Configuration
    • Configuration in pyproject.toml
    • Configuration Output
      • Effective Configuration (rumdl config)
      • Defaults Only (rumdl config --defaults)
  • 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)

  • Options:
    • -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)
    • --no-respect-gitignore: Don't respect .gitignore files
    • -v, --verbose: Show detailed output
    • --profile: Show profiling information
    • -q, --quiet: Suppress all output except errors

• init: Create a default .rumdl.toml configuration file in the current directory

  • --pyproject: Generate configuration for pyproject.toml instead of .rumdl.toml

• rule [<rule>]: Show information about a rule or list all rules

  • If a rule name or ID is provided, shows details for that rule
  • If no argument is given, lists all available rules

• config [--defaults]: Show the full effective configuration (default), or only the defaults.

  • --defaults: Show only the default configuration as TOML.
  • Subcommands:
    • get <key>: Query a specific config key (e.g. global.exclude or MD013.line_length)

• version: Show version information

Usage Examples

# Lint all Markdown files in the current directory
rumdl check .

# Automatically fix issues
rumdl check --fix .

# Create a default configuration file
rumdl init

# Create or update a pyproject.toml file with rumdl configuration
rumdl init --pyproject

# Show information about a specific rule
rumdl rule MD013

# List all available rules
rumdl rule

# Query a specific config key
rumdl config get global.exclude

# Show version information
rumdl version

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.

Configuration Output

Effective Configuration (rumdl config)

The rumdl config command prints the full effective configuration (defaults + all overrides), showing every key and its value, annotated with the source of each value. The output is colorized and the [from ...] annotation is globally aligned for easy scanning.

Example output:

[global]
  enable             = []                             [from default]
  disable            = ["MD033"]                      [from .rumdl.toml]
  include            = ["README.md"]                  [from .rumdl.toml]
  respect_gitignore  = true                           [from .rumdl.toml]

[MD013]
  line_length        = 200                            [from .rumdl.toml]
  code_blocks        = true                           [from .rumdl.toml]
  ...

• Keys are cyan, values are yellow, and the [from ...] annotation is colored by source:
  • Green: CLI
  • Blue: .rumdl.toml
  • Magenta: pyproject.toml
  • Yellow: default
• The [from ...] column is aligned across all sections.

Defaults Only (rumdl config --defaults)

The --defaults flag prints only the default configuration as TOML, suitable for copy-paste or reference:

[global]
enable = []
disable = []
exclude = []
include = []
respect_gitignore = true

[MD013]
line_length = 80
code_blocks = true
...

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.