rumdl 0.0.42

An extremely fast Markdown linter written in Rust

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
  • Rules
  • Command-line Interface
    • Commands
    • Options
  • Configuration
    • Configuration File Example
    • Initializing Configuration
    • Configuration in pyproject.toml
  • Output Style
    • Output Format
  • Development
    • Prerequisites
    • Building
    • Testing
  • Using rumdl with pre-commit
  • 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" .

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

Rules

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

Category	Description	Example Rules
Headings	Proper heading structure and formatting	MD001, MD002, MD003
Lists	Consistent list formatting and structure	MD004, MD005, MD007
Whitespace	Proper spacing and line length	MD009, MD010, MD012
Code	Code block formatting and language tags	MD040, MD046, MD048
Links	Proper link and reference formatting	MD034, MD039, MD042
Images	Image alt text and references	MD045, MD052
Style	Consistent style across document	MD031, MD032, MD035

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 (default: true)
• --no-respect-gitignore: Don't respect .gitignore files (same as --ignore-gitignore)
• --ignore-gitignore: Ignore .gitignore files when scanning directories (deprecated, use --no-respect-gitignore)
• -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

Using rumdl with pre-commit (for Users)

You can use rumdl as a pre-commit hook in your own projects to check your Markdown files.

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

repos:
-   repo: https://github.com/rvben/rumdl
    rev: v0.5.0  # Use the latest release tag
    hooks:
    -   id: rumdl-check  # Just check for issues
    # Or use rumdl-fix to automatically fix issues:
    # -   id: rumdl-fix

Then run pre-commit install.

Pre-commit will automatically download and install rumdl using cargo. rumdl will respect any .rumdl.toml or pyproject.toml configuration file present in your repository.

License

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