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
  • Rules
  • Command-line Interface
    • Commands
    • Options
  • Configuration
  • Output Style
    • Output Format
  • Development
    • Prerequisites
    • Building
    • Testing
  • License

Quick Start

# Install using Cargo
cargo install rumdl

# Check Markdown files in the current directory
rumdl .

# Automatically fix issues
rumdl --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:

# Check a single file
rumdl README.md

# Check all Markdown files in current directory and subdirectories
rumdl .

# Automatically fix issues
rumdl --fix README.md

# Create a default configuration file
rumdl init

Common usage examples:

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

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

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

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

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

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

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 [options] [file or directory...]
rumdl <command> [options]

Commands

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

Options

• -c, --config <file>: Use custom configuration file
• -f, --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
• -v, --verbose: Show detailed output

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

MIT License