# Install using Cargo
cargo install rumdl
# Lint Markdown files in the current directory
rumdl check .
# Format files (exits 0 on success, even if unfixable violations remain)
rumdl fmt .
# Auto-fix and report unfixable violations (exits 1 if violations remain)
rumdl check --fix .
# Create a default configuration file
rumdl initrumdl is a high-performance Markdown linter and formatter that helps ensure consistency and best practices in your Markdown files. Inspired by ruff 's approach to Python linting, rumdl brings similar speed and developer experience improvements to the Markdown ecosystem.
It offers:
- ⚡️ Built for speed with Rust - significantly faster than alternatives
- 🔍 54 lint rules covering common Markdown issues
- 🛠️ Automatic formatting with
--fixfor files and stdin/stdout - 📦 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
rumdl is designed for speed. Benchmarked on the Rust Book repository (478 markdown files, October 2025):
With intelligent caching, subsequent runs are even faster - rumdl only re-lints files that have changed, making it ideal for watch mode and editor integration.
- rumdl - A high-performance Markdown linter, written in Rust
- A modern Markdown linter and formatter, built for speed with Rust
- Quick Start
- Overview
- Table of Contents
- Installation
- Usage
- Pre-commit Integration
- CI/CD Integration
- Rules
- Command-line Interface
- Configuration
- Output Style
- Development
- License
Choose the installation method that works best for you:
brew install rumdlcargo install rumdlpip install rumdlFor faster installation and better dependency management with uv:
# Install directly
uv tool install rumdl
# Or run without installing
uv tool run rumdl check .nix-channel --update
nix-env --install --attr nixpkgs.rumdlAlternatively, you can use flakes to run it without installation.
nix run --extra-experimental-features 'flakes nix-command' nixpkgs/nixpkgs-unstable#rumdl -- --versionAfter enabling the TUR repo using
pkg install tur-repopkg install rumdl
rumdl is available on the AUR:
You can install it using your AUR helper of choice.
yay -Sy rumdl
# OR
yay -Sy rumdl-bin# 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"For the best development experience, install the rumdl VS Code extension directly from the command line:
# Install the VS Code extension
rumdl vscode
# Check if the extension is installed
rumdl vscode --status
# Force reinstall the extension
rumdl vscode --forceThe extension provides:
- 🔍 Real-time linting as you type
- 💡 Quick fixes for common issues
- 🎨 Code formatting on save
- 📋 Hover tooltips with rule documentation
- ⚡ Lightning-fast performance with zero lag
The CLI will automatically detect VS Code, Cursor, or Windsurf and install the appropriate extension. See the VS Code extension documentation for more details.
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 .
# Format a specific file
rumdl fmt README.md
# Create a default configuration file
rumdl initCommon 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" .
# Watch mode for continuous linting
rumdl check --watch docs/
# Combine include and exclude patterns
rumdl check --include "docs/**/*.md" --exclude "docs/temp,docs/drafts" .
# Don't respect gitignore files (note: --respect-gitignore defaults to true)
rumdl check --respect-gitignore=false .
# Force exclude patterns even for explicitly specified files (useful for pre-commit)
rumdl check excluded.md --force-exclude # Will respect exclude patterns in configrumdl supports formatting via stdin/stdout, making it ideal for editor integrations and CI pipelines:
# Format content from stdin and output to stdout
cat README.md | rumdl fmt - > README_formatted.md
# Alternative: cat README.md | rumdl fmt --stdin > README_formatted.md
# Use in a pipeline
echo "# Title " | rumdl fmt -
# Output: # Title
# Format clipboard content (macOS example)
pbpaste | rumdl fmt - | pbcopy
# Provide filename context for better error messages (useful for editor integrations)
cat README.md | rumdl check - --stdin-filename README.mdFor editor integration, use stdin/stdout mode with the --quiet flag to suppress diagnostic messages:
# Format selection in editor (example for vim)
:'<,'>!rumdl fmt - --quiet
# Format entire buffer
:%!rumdl fmt - --quietYou can use rumdl as a pre-commit hook to check and format your Markdown files.
The recommended way is to use the official pre-commit hook repository:
Add the following to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/rvben/rumdl-pre-commit
rev: v0.0.193
hooks:
- id: rumdl # Lint only (fails on issues)
- id: rumdl-fmt # Auto-format (fixes what it can)Two hooks are available:
rumdl— Lints files and fails if any issues are found (ideal for CI)rumdl-fmt— Auto-formats files (fixes what it can, always succeeds)
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.
By default, when pre-commit passes files explicitly to rumdl, the exclude patterns in your .rumdl.toml configuration file are ignored. This is intentional behavior - if you explicitly specify a
file, it gets checked.
However, for pre-commit workflows where you want to exclude certain files even when they're passed explicitly, you have two options:
-
Use
force_excludein your configuration file:# .rumdl.toml [global] exclude = ["generated/*.md", "vendor/**"] force_exclude = true # Enforce excludes even for explicitly provided files
-
Use the
--force-excludeflag in your pre-commit config:repos: - repo: https://github.com/rvben/rumdl-pre-commit rev: v0.0.193 hooks: - id: rumdl args: [--force-exclude] # Respect exclude patterns from config
We have a companion Action you can use to integrate rumdl directly in your workflow:
jobs:
rumdl-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: rvben/rumdl@v0The v0 tag always points to the latest stable release, following GitHub Actions conventions.
| Input | Description | Default |
|---|---|---|
version |
Version of rumdl to install | latest |
path |
Path to lint | workspace root |
config |
Path to config file | auto-detected |
report-type |
Output format: logs or annotations |
logs |
Lint specific directory with pinned version:
- uses: rvben/rumdl@v0
with:
version: "0.0.189"
path: docs/Use custom config and show annotations in PR:
- uses: rvben/rumdl@v0
with:
config: .rumdl.toml
report-type: annotationsThe annotations report type displays issues directly in the PR's "Files changed" tab with error/warning severity levels and precise locations.
rumdl implements 54 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 rulerumdl <command> [options] [file or directory...]Lint Markdown files and print warnings/errors (main subcommand)
Arguments:
[PATHS...]: Files or directories to lint. If provided, these paths take precedence over include patterns
Options:
-f, --fix: Automatically fix issues where possible--diff: Show diff of what would be fixed instead of fixing files-w, --watch: Run in watch mode by re-running whenever files change-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 (does not apply to explicitly provided paths)--force-exclude: Enforce exclude patterns even for explicitly specified files (useful for pre-commit hooks)-v, --verbose: Show detailed output--profile: Show profiling information--statistics: Show rule violation statistics summary-q, --quiet: Quiet mode-o, --output <format>: Output format:text(default) orjson--stdin: Read from stdin instead of files
Format Markdown files and output the result. Always exits with code 0 on successful formatting, making it ideal for editor integration.
Arguments:
[PATHS...]: Files or directories to format. If provided, these paths take precedence over include patterns
Options:
All the same options as check are available (except --fix which is always enabled), including:
--stdin: Format content from stdin and output to stdout-d, --disable <rules>: Disable specific rules during formatting-e, --enable <rules>: Format using only specific rules--exclude/--include: Control which files to format-q, --quiet: Suppress diagnostic output
Examples:
# Format all Markdown files in current directory
rumdl fmt
# Format specific file
rumdl fmt README.md
# Format from stdin (using dash syntax)
cat README.md | rumdl fmt - > formatted.md
# Alternative: cat README.md | rumdl fmt --stdin > formatted.mdCreate a default configuration file in the current directory
Options:
--pyproject: Generate configuration forpyproject.tomlinstead of.rumdl.toml
Import and convert markdownlint configuration files to rumdl format
Arguments:
<FILE>: Path to markdownlint config file (JSON/YAML)
Options:
-o, --output <path>: Output file path (default:.rumdl.toml)--format <format>: Output format:tomlorjson(default:toml)--dry-run: Show converted config without writing to file
Show information about a rule or list all rules
Arguments:
[rule]: Rule name or ID (optional). If provided, shows details for that rule. If omitted, lists all available rules
Show configuration or query a specific key
Options:
--defaults: Show only the default configuration values--output <format>: Output format (e.g.toml,json)
Subcommands:
get <key>: Query a specific config key (e.g.global.excludeorMD013.line_length)file: Show the absolute path of the configuration file that was loaded
Start the Language Server Protocol server for editor integration
Options:
--port <PORT>: TCP port to listen on (for debugging)--stdio: Use stdio for communication (default)-v, --verbose: Enable verbose logging
Install the rumdl VS Code extension
Options:
--force: Force reinstall even if already installed--status: Show installation status without installing
Show version information
These options are available for all commands:
--color <mode>: Control colored output:auto(default),always,never--config <file>: Path to configuration file--no-config: Ignore all configuration files and use built-in defaults
0: Success1: Violations found (or remain after--fix)2: Tool error
Note: rumdl fmt exits 0 on successful formatting (even if unfixable violations remain), making it compatible with editor integrations. rumdl check --fix exits 1 if violations remain, useful
for pre-commit hooks.
# Lint all Markdown files in the current directory
rumdl check .
# Format files (exits 0 on success, even if unfixable violations remain)
rumdl fmt .
# Auto-fix and report unfixable violations (exits 1 if violations remain)
rumdl check --fix .
# Preview what would be fixed without modifying files
rumdl check --diff .
# Create a default configuration file
rumdl init
# Create or update a pyproject.toml file with rumdl configuration
rumdl init --pyproject
# Import a markdownlint config file
rumdl import .markdownlint.json
# Convert markdownlint config to JSON format
rumdl import --format json .markdownlint.yaml --output rumdl-config.json
# Preview conversion without writing file
rumdl import --dry-run .markdownlint.json
# 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 the path of the loaded configuration file
rumdl config file
# Show configuration as JSON instead of the default format
rumdl config --output json
# Lint content from stdin
echo "# My Heading" | rumdl check --stdin
# Get JSON output for integration with other tools
rumdl check --output json README.md
# Show statistics summary of rule violations
rumdl check --statistics .
# Disable colors in output
rumdl check --color never README.md
# Use built-in defaults, ignoring all config files
rumdl check --no-config README.md
# Show version information
rumdl versionrumdl can be configured in several ways:
- Using a
.rumdl.tomlorrumdl.tomlfile in your project directory or parent directories - Using a
.config/rumdl.tomlfile (following the config-dir convention) - Using the
[tool.rumdl]section in your project'spyproject.tomlfile (for Python projects) - Using command-line arguments
- Automatic markdownlint compatibility: rumdl automatically discovers and loads existing markdownlint config files (
.markdownlint.json,.markdownlint.yaml, etc.)
rumdl automatically searches for configuration files by traversing up the directory tree from the current working directory, similar to tools like git , ruff , and eslint . This means you can
run rumdl from any subdirectory of your project and it will find the configuration file at the project root.
The search follows these rules:
- Searches upward for
.rumdl.toml,rumdl.toml,.config/rumdl.toml, orpyproject.toml(with[tool.rumdl]section) - Precedence order:
.rumdl.toml>rumdl.toml>.config/rumdl.toml>pyproject.toml - Stops at the first configuration file found
- Stops searching when it encounters a
.gitdirectory (project boundary) - Maximum traversal depth of 100 directories
- Falls back to user configuration if no project configuration is found (see Global Configuration below)
To disable all configuration discovery and use only built-in defaults, use the --isolated flag:
# Use discovered configuration (default behavior)
rumdl check .
# Ignore all configuration files
rumdl check --isolated .rumdl provides a JSON Schema for .rumdl.toml configuration files, enabling autocomplete, validation, and inline documentation in supported editors like VS Code, IntelliJ IDEA, and others.
The schema is available at https://raw.githubusercontent.com/rvben/rumdl/main/rumdl.schema.json.
VS Code Setup:
- Install the "Even Better TOML" extension
- The schema will be automatically associated with
.rumdl.tomlandrumdl.tomlfiles once submitted to SchemaStore
Manual Schema Association:
Add this to your .rumdl.toml file (in a comment, as TOML doesn't support $schema):
# yaml-language-server: $schema=https://raw.githubusercontent.com/rvben/rumdl/main/rumdl.schema.jsonThis enables IntelliSense, validation, and hover documentation for all configuration options.
When no project configuration is found, rumdl will check for a user-level configuration file in your platform's standard config directory:
Location:
- Linux/macOS:
~/.config/rumdl/(respectsXDG_CONFIG_HOMEif set) - Windows:
%APPDATA%\rumdl\
Files checked (in order):
.rumdl.tomlrumdl.tomlpyproject.toml(must contain[tool.rumdl]section)
This allows you to set personal preferences that apply to all projects without local configuration.
Example: Create ~/.config/rumdl/rumdl.toml:
[global]
line-length = 100
disable = ["MD013", "MD041"]
[MD007]
indent = 2Note: User configuration is only used when no project configuration exists. Project configurations always take precedence.
rumdl provides seamless compatibility with existing markdownlint configurations:
** Automatic Discovery**: rumdl automatically detects and loads markdownlint config files:
.markdownlint.json/.markdownlint.jsonc.markdownlint.yaml/.markdownlint.ymlmarkdownlint.json/markdownlint.yaml
** Explicit Import**: Convert markdownlint configs to rumdl format:
# Convert to .rumdl.toml
rumdl import .markdownlint.json
# Convert to JSON format
rumdl import --format json .markdownlint.yaml --output config.json
# Preview conversion
rumdl import --dry-run .markdownlint.jsonFor comprehensive documentation on global settings (file selection, rule enablement, etc.), see our Global Settings Reference.
rumdl supports inline HTML comments to disable or configure rules for specific sections of your Markdown files. This is useful for making exceptions without changing global configuration:
<!-- rumdl-disable MD013 -->
This line can be as long as needed without triggering the line length rule.
<!-- rumdl-enable MD013 -->Note: markdownlint-disable/markdownlint-enable comments are also supported for compatibility with existing markdownlint configurations.
For complete documentation on inline configuration options, see our Inline Configuration Reference.
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"]
# Disable specific rules for specific files
[per-file-ignores]
"README.md" = ["MD033"] # Allow HTML in README
"SUMMARY.md" = ["MD025"] # Allow multiple H1 in table of contents
"docs/api/**/*.md" = ["MD013", "MD041"] # Relax rules for generated docs
# Configure individual rules
[MD007]
indent = 2
[MD013]
line-length = 100
code-blocks = false
tables = false
reflow = true # Enable automatic line wrapping (required for --fix)
[MD025]
level = 1
front-matter-title = "title"
[MD044]
names = ["rumdl", "Markdown", "GitHub"]
[MD048]
code-fence-style = "backtick"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 --pyprojectFor 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.
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.
[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.
The --defaults flag prints only the default configuration as TOML, suitable for copy-paste or reference:
[global]
enable = []
disable = []
exclude = []
include = []
respect_gitignore = true
force_exclude = false # Set to true to exclude files even when explicitly specified
[MD013]
line_length = 80
code_blocks = true
...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 `rumdl fmt` to automatically fix issues
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
For integration with other tools and automation, use --output json:
rumdl check --output json README.mdThis produces structured JSON output:
{
"summary": {
"total_files": 1,
"files_with_issues": 1,
"total_issues": 2,
"fixable_issues": 1
},
"files": [
{
"path": "README.md",
"issues": [
{
"line": 12,
"column": 1,
"rule": "MD022",
"message": "Headings should be surrounded by blank lines",
"fixable": true,
"severity": "error"
}
]
}
]
}- Rust 1.91 or higher
- Make (for development commands)
make buildmake testIf you modify the configuration structures in src/config.rs, regenerate the JSON schema:
# Generate/update the schema
make schema
# Or: rumdl schema generate
# Check if schema is up-to-date (useful in CI)
make check-schema
# Or: rumdl schema check
# Print schema to stdout
rumdl schema printThe schema is automatically generated from the Rust types using schemars and should be kept in sync with the configuration structures.
rumdl is licensed under the MIT License. See the LICENSE file for details.
