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

Quick Start

# 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 0 if all fixed, 1 if violations remain)
rumdl check --fix .

# Create a default configuration file
rumdl init

Overview

rumdl 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.

Questions or feedback? Join us on Discord.

It offers:

• ⚡️ Built for speed with Rust - significantly faster than alternatives
• 🔍 77 lint rules covering common Markdown issues
• 🛠️ Automatic formatting with --fix for files and stdin/stdout
• 📦 Zero dependencies - single binary with no runtime requirements
• 🔧 Highly configurable with TOML-based config files
• 🎯 Multiple Markdown flavors - GFM, MkDocs, MDX, Quarto, MyST support with auto-detection
• 🌐 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

Performance

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.

Table of Contents

• Installation
  • Using Homebrew (macOS/Linux)
  • Using Cargo (Rust)
  • Using npm
  • Using pip (Python)
  • Using uv
  • Using mise
  • Using Nix (macOS/Linux)
  • Using Termux User Repository (TUR) (Android)
  • Using pacman (Arch Linux)
  • Download binary
  • Editor Plugins
  • Shell Completions
• Usage
  • Stdin/Stdout Formatting
  • Editor Integration
• Pre-commit Integration
  • Excluding Files in Pre-commit
• CI/CD Integration
  • GitHub Actions
    • Inputs
    • Examples
• Rules
• Flavors
  • Supported Flavors
  • Configuring Flavors
• Command-line Interface
  • Commands
    • check [PATHS...]
    • fmt [PATHS...]
    • init [OPTIONS]
    • import <FILE> [OPTIONS]
    • rule [<rule>]
    • config [OPTIONS] [COMMAND]
    • server [OPTIONS]
    • vscode [OPTIONS]
    • completions [SHELL]
    • version
  • Global Options
  • Exit Codes
  • Usage Examples
• LSP
• Configuration
  • Configuration Discovery
  • Editor Support (JSON Schema)
  • Global Configuration
  • Markdownlint Migration
  • Inline Configuration
  • Configuration File Example
  • Style Guide Presets
  • Initializing Configuration
  • Configuration in pyproject.toml
  • Configuration Output
    • Effective Configuration (rumdl config)
    • Example output
  • Defaults Only (rumdl config --defaults)
  • Non-Defaults Only (rumdl config --no-defaults)
• Output Style
  • Output Format
    • Text Output (Default)
    • JSON Output
• Stability
• Development
  • Prerequisites
  • Building
  • Testing
  • JSON Schema Generation
• Used By
• Sponsors
• License

Installation

Choose the installation method that works best for you:

Using winget (Windows)

winget install --id rvben.rumdl --exact

Using Homebrew (macOS/Linux)

brew install rumdl

Using Cargo (Rust)

cargo install rumdl

Using npm

npm install -g rumdl

Or as a dev dependency:

npm install --save-dev rumdl

Using pip (Python)

pip install rumdl

Using uv

For faster installation and better dependency management with uv:

# Install directly
uv tool install rumdl

# Or run without installing
uvx rumdl check .

Using mise

For dependency management with mise:

# List available versions
mise ls-remote rumdl

# Install the latest version
mise install rumdl

# Use a specific version for the project
mise use rumdl@0.2.42

Using Nix (macOS/Linux)

nix-channel --update
nix-env --install --attr nixpkgs.rumdl

Alternatively, you can use flakes to run it without installation.

nix run --extra-experimental-features 'flakes nix-command' nixpkgs/nixpkgs-unstable#rumdl -- --version

Using Termux User Repository (TUR) (Android)

After enabling the TUR repo using

pkg install tur-repo

pkg install rumdl

Using pacman (Arch Linux)

rumdl is available in the official Arch Linux repositories:

pacman -S 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"

Using Docker

Multi-arch images (amd64, arm64) are published to the GitHub Container Registry on every release. Mount your project at /data (the working directory inside the container):

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/data" ghcr.io/rvben/rumdl:latest check .

# Pin a specific version
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/data" ghcr.io/rvben/rumdl:0.3.0 check .

The image runs as a non-root user by default, so it never writes root-owned files into your project. Passing --user runs rumdl as your own user, which lets the lint cache (.rumdl_cache) be written into the mounted project with your ownership; without it the cache is skipped gracefully. The image contains only the static rumdl binary, so there is no shell to enter; pass rumdl arguments directly.

For environments that need a shell inside the image, such as GitLab CI job containers, an Alpine-based flavour is published as ghcr.io/rvben/rumdl:alpine (or pin :<version>-alpine). It has no rumdl entrypoint; invoke the binary by name:

docker run --rm -v "$PWD:/data" ghcr.io/rvben/rumdl:alpine rumdl check .

# .gitlab-ci.yml
lint-markdown:
  image: ghcr.io/rvben/rumdl:alpine
  script:
    - rumdl check .

Editor Plugins

All plugins provide real-time linting, formatting on save, hover documentation, and automatic configuration discovery.

Shell Completions

rumdl can generate tab-completion scripts via rumdl completions [SHELL]. Supported shells: bash, zsh, fish, powershell, elvish.

When SHELL is omitted, rumdl auto-detects it from $SHELL. Run rumdl completions --list to see all supported shells.

Bash — add to ~/.bashrc:

source <(rumdl completions bash)

Zsh — add to ~/.zshrc:

source <(rumdl completions zsh)

Or install system-wide for zsh:

rumdl completions zsh > "${fpath[1]}/_rumdl"

Fish — write the completion file once:

rumdl completions fish > ~/.config/fish/completions/rumdl.fish

PowerShell — add to your $PROFILE:

rumdl completions powershell | Out-String | Invoke-Expression

Elvish — add to ~/.config/elvish/rc.elv:

eval (rumdl completions elvish | slurp)

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 .

# Format a specific file
rumdl fmt README.md

# Create a default configuration file
rumdl init

Common usage examples:

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

# Override config inline without touching any file (Ruff-compatible syntax)
rumdl check --config 'MD013.line-length=120' --config 'MD013.reflow=true' docs/
# See docs/cli-config-overrides.md for the full reference.

# 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 .

# Disable all exclude patterns from config
rumdl check excluded.md --no-exclude

Stdin/Stdout Formatting

rumdl 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 --silent - > README_formatted.md
# Alternative: cat README.md | rumdl fmt --silent --stdin > README_formatted.md

# Use in a pipeline
echo "# Title   " | rumdl fmt --silent -
# Output: # Title

# Format clipboard content (macOS example)
pbpaste | rumdl fmt --silent - | pbcopy

# Provide filename context for better error messages (useful for editor integrations)
cat README.md | rumdl check - --stdin-filename README.md

Use --silent whenever stdout should contain only formatted Markdown. Plain rumdl fmt - may also emit remaining diagnostics.

Editor Integration

For editor integration, use stdin/stdout mode with the --silent flag when you want pure formatted output on stdout. Use --quiet if you still want diagnostics but want to suppress summary lines:

# Format selection in editor (example for vim)
:'<,'>!rumdl fmt - --silent

# Format entire buffer
:%!rumdl fmt - --silent

Pre-commit Integration

You 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:

rumdl-pre-commit repository

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

repos:
  - repo: https://github.com/rvben/rumdl-pre-commit
    rev: v0.2.42
    hooks:
      - id: rumdl      # Lint only; add args [--fix] to auto-fix
      - id: rumdl-fmt  # Pure format, always exits 0

Two hooks are available:

• rumdl - Lints files and exits 1 if violations are found; non-destructive by default (recommended as the primary hook)
• rumdl-fmt - Formats files in place and always exits 0; relies on pre-commit's file-change detection

This mirrors the ruff + ruff-format split: the linter hook reports by default and never rewrites your files unless you opt in. To auto-fix violations in place, add args: [--fix]:

repos:
  - repo: https://github.com/rvben/rumdl-pre-commit
    rev: v0.2.42
    hooks:
      - id: rumdl
        args: [--fix]  # Auto-fix violations in place

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.

Excluding Files in Pre-commit

By default, when pre-commit explicitly passes files to rumdl, the exclude patterns defined in your .rumdl.toml configuration file are respected.

However, for pre-commit workflows where you want to include all files, even when they're excluded in the config, you can use the --no-exclude flag in your pre-commit config, e.g.:

repos:
  - repo: https://github.com/rvben/rumdl-pre-commit
    rev: v0.2.42
    hooks:
      - id: rumdl
        args: [--no-exclude]  # Disable all exclude patterns

CI/CD Integration

GitHub Actions

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@v0

The v0 tag always points to the latest stable release, following GitHub Actions conventions.

Inputs

Examples

Lint specific directory with pinned version:

- uses: rvben/rumdl@v0
  with:
    version: "0.1.71"
    path: docs/

Use custom config and show annotations in PR:

- uses: rvben/rumdl@v0
  with:
    config: .rumdl.toml
    report-type: annotations

The annotations report type displays issues directly in the PR's "Files changed" tab with error/warning severity levels and precise locations. The action ref (rvben/rumdl@v0) selects the GitHub Action version, while the optional version input pins the rumdl CLI version installed inside the workflow.

Rules

rumdl implements 77 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 rule

Flavors

rumdl supports multiple Markdown flavors to accommodate different documentation systems. Each flavor adjusts rule behavior for syntax specific to that system, reducing false positives.

Supported Flavors

Configuring Flavors

Set a global flavor in your configuration:

[global]
flavor = "mkdocs"

Or configure per-file patterns:

[per-file-flavor]
"docs/**/*.md" = "mkdocs"
"**/*.mdx" = "mdx"
"**/*.qmd" = "quarto"

When no flavor is configured, rumdl auto-detects based on file extension (.mdx → mdx, .qmd/.Rmd → quarto, .md → standard).

For complete flavor documentation, see the Flavors Guide.

Command-line Interface

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

Commands

check [PATHS...]

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
• -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)
• --no-exclude: Disable all exclude patterns from config
• -v, --verbose: Show detailed output
• --profile: Show profiling information
• --statistics: Show rule violation statistics summary
• -q, --quiet: Print diagnostics, but suppress summary lines
• --output-format <format>: Output format for diagnostics
• --stdin: Read from stdin instead of files

fmt [PATHS...]

Format Markdown files and apply fixes. Unlike check --fix, fmt keeps formatter-style exit codes and exits 0 after 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: Print diagnostics, but suppress summary lines
• -s, --silent: Suppress diagnostics and summaries for pure formatter 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 --silent - > formatted.md
# Alternative: cat README.md | rumdl fmt --silent --stdin > formatted.md

init [OPTIONS]

Create a default configuration file in the current directory

Options:

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

import <FILE> [OPTIONS]

Import and convert markdownlint configuration files to rumdl format

Arguments:

• <FILE>: Path to markdownlint config file (JSON/JSONC/YAML)

Options:

• -o, --output <path>: Output file path (default: .rumdl.toml)
• --format <format>: Output format: toml or json (default: toml)
• --dry-run: Show converted config without writing to file

rule [<rule>]

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

Useful options:

• --list-categories: List available rule categories and exit
• --category <name>: Filter rules by category when listing
• --output-format <format>: Emit structured output such as json or json-lines
• --explain: Include full documentation in json and json-lines output

config [OPTIONS] [COMMAND]

Show configuration or query a specific key

Options:

• --defaults: Show only the default configuration values
• --no-defaults: Show only non-default configuration values (exclude defaults)
• --output <format>: Output format (e.g. toml, json)

Subcommands:

• get <key>: Query a specific config key (e.g. global.exclude or MD013.line_length)
• file: Show the absolute path of the configuration file that was loaded

server [OPTIONS]

Start the Language Server Protocol server for editor integration

Options:

• --port <PORT>: TCP port to listen on (for debugging)
• -v, --verbose: Enable verbose logging

vscode [OPTIONS]

Install the rumdl VS Code extension

Options:

• --force: Force reinstall even if already installed
• --update: Update to the latest version (only if newer version is available)
• --status: Show installation status without installing

completions [SHELL]

Print a shell completion script for rumdl to stdout. See Shell Completions for installation snippets.

Arguments:

• [SHELL]: One of bash, zsh, fish, powershell, elvish. Auto-detected from $SHELL when omitted.

Options:

• -l, --list: List available shells and exit

version

Show version information

Global Options

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
• --isolated: Hidden compatibility alias for --no-config

Exit Codes

• 0: Success (no violations found, or all violations were fixed)
• 1: 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 0 if all violations are fixed, or 1 if violations remain after fixing (useful for pre-commit hooks and CI/CD).

Usage Examples

# 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 0 if all fixed, 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

# Show only non-default configuration values
rumdl config --no-defaults

# Lint content from stdin
echo "# My Heading" | rumdl check --stdin

# Get JSON output for integration with other tools
rumdl check --output-format 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 version

LSP

rumdl is also available as an LSP server for editor integration.

For editors that support generic LSP configuration, the minimal stdio setup is:

command = ["rumdl", "server"]

For editor-specific information on setting up the LSP, refer to our LSP documentation

Configuration

rumdl can be configured in several ways:

1. Using a .rumdl.toml or rumdl.toml file in your project directory or parent directories
2. Using a <project>/.config/rumdl.toml file (following the config-dir convention)
3. Using the [tool.rumdl] section in your project's pyproject.toml file (for Python projects)
4. Using command-line arguments
5. Using a global user config at ~/.config/rumdl/rumdl.toml or a home-directory dotfile at ~/.rumdl.toml (see Global Configuration below)
6. Automatic markdownlint compatibility: rumdl automatically discovers and loads existing markdownlint config files (.markdownlint.json, .markdownlint.yaml, etc.)

Configuration Discovery

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, <dir>/.config/rumdl.toml, or pyproject.toml (with [tool.rumdl] section)
• Precedence order: .rumdl.toml > rumdl.toml > <dir>/.config/rumdl.toml > pyproject.toml
• Stops at the first configuration file found
• Warns when more than one of these files exists in the same directory, so you can tell which is winning (rumdl config file prints the loaded config's path)
• Stops searching when it encounters a .git directory (project boundary)
• Maximum traversal depth of 100 directories
• Falls back to markdownlint config files (.markdownlint.yaml, etc.) using the same upward traversal
• Falls back to user configuration if no project configuration is found (see Global Configuration below)

Per-Directory Configuration

When running rumdl check . from the project root, rumdl resolves configuration on a per-directory basis. Files in subdirectories with their own .rumdl.toml use that config instead of the root config. This matches the behavior of Ruff and markdownlint-cli2.

Subdirectory configs are standalone by default. Use extends to inherit from a parent config:

# docs/.rumdl.toml — inherits root config, overrides line-length
extends = "../.rumdl.toml"

[global]
line-length = 120

extends paths support ~/, absolute, and relative paths, plus $VAR / ${VAR} environment-variable expansion (e.g. extends = "$GEM_PATH/gems/my-style/.rumdl.toml") for a base config delivered at a machine-dependent location. See Config inheritance for details.

Per-directory resolution is disabled when --config or --no-config is used (--isolated is still accepted as a compatibility alias).

To disable all configuration discovery and use only built-in defaults, use the --no-config flag:

# Use discovered configuration (default behavior)
rumdl check .

# Ignore all configuration files
rumdl check --no-config .

Editor Support (JSON Schema)

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.

Automatic Setup (via SchemaStore):

The schema is registered with SchemaStore, so editors with TOML support will automatically provide autocomplete and validation for .rumdl.toml and rumdl.toml files.

VS Code: Install the "Even Better TOML" extension - schema association is automatic.

Manual Schema Association:

If your editor doesn't support SchemaStore, associate this schema URL with .rumdl.toml or rumdl.toml in the editor's TOML schema settings:

https://raw.githubusercontent.com/rvben/rumdl/main/rumdl.schema.json

Global Configuration

When no project configuration is found, rumdl looks for a user-level configuration file in two locations, in this order:

1. Platform user-config directory (preferred):

• Linux/macOS: ~/.config/rumdl/ (respects XDG_CONFIG_HOME if set)
• Windows: %APPDATA%\rumdl\

Files checked (in order): .rumdl.toml, rumdl.toml, pyproject.toml (must contain [tool.rumdl] section).

2. Home-directory dotfile (fallback):

If nothing is found in the platform config directory, rumdl also checks for ~/.rumdl.toml, then ~/rumdl.toml. This honors the classic Unix dotfile convention used by tools like git and npm.

This allows you to set personal preferences that apply to all projects without local configuration.

Example: Create ~/.config/rumdl/rumdl.toml (preferred) or ~/.rumdl.toml:

[global]
line-length = 100
disable = ["MD013", "MD041"]

[MD007]
indent = 2

Note: User configuration is only used when no project configuration exists. Project configurations always take precedence. When both a platform user-config file and a home-directory dotfile exist, the platform user-config file wins.

Markdownlint Migration

rumdl provides seamless compatibility with existing markdownlint configurations:

Automatic Discovery: rumdl automatically detects and loads markdownlint config files by traversing up the directory tree (just like .rumdl.toml):

• .markdownlint.json / .markdownlint.jsonc
• .markdownlint.yaml / .markdownlint.yml
• markdownlint.json / markdownlint.yaml

This means you can place a .markdownlint.yaml at your project root and run rumdl from any subdirectory - it will find and use the config automatically.

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.json

For comprehensive documentation on global settings (file selection, rule enablement, etc.), see our Global Settings Reference.

Inline Configuration

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.

Configuration File Example

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

[global]
line-length = 100
exclude = ["node_modules", "build", "dist"]
respect-gitignore = true
flavor = "mkdocs"  # Use MkDocs flavor (see Flavors section)
disable = ["MD013", "MD033"]

# Per-file flavor overrides
[per-file-flavor]
"**/*.mdx" = "mdx"

# 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"

# Code block tools (optional)
[code-block-tools]
enabled = true
normalize-language = "linguist"
on-error = "warn"
timeout = 30000

[code-block-tools.language-aliases]
py = "python"
bash = "shell"

[code-block-tools.languages.python]
lint = ["ruff:check"]
format = ["ruff:format"]

Style Guide Presets

Ready-to-use configurations for popular style guides are available in the examples/ directory:

• Google Style - Google's Markdown style guide
• Prettier-compatible - Aligns with Prettier's markdown formatting

Copy one to your project as .rumdl.toml to use it.

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"]
respect-gitignore = true

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

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

Both kebab-case (line-length, respect-gitignore) and snake_case (line_length, respect_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 rumdl config --defaults command shows only the default configuration values, useful for understanding what the built-in defaults are.

Non-Defaults Only (rumdl config --no-defaults)

The rumdl config --no-defaults command shows only configuration values that differ from defaults, making it easy to see what you've customized. This is particularly useful when you want to see only your project-specific or user-specific overrides without the noise of default values.

Example:

$ rumdl config --no-defaults
[global]
disable = ["MD013"]                    [from project config]
line_length = 100                      [from pyproject.toml]

[MD004]
style = "asterisk"                     [from project config]

This helps you quickly identify what customizations you've made to the default configuration.

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
...

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 `rumdl fmt` to automatically fix issues

Output Format

Text Output (Default)

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

JSON Output

For integration with other tools and automation, use --output-format json:

rumdl check --output-format json README.md

This produces a flat JSON array of warning objects, one per issue. Fixable issues include a fix object with the byte range to replace and the replacement text:

[
  {
    "file": "README.md",
    "line": 12,
    "column": 1,
    "rule": "MD022",
    "message": "Headings should be surrounded by blank lines",
    "severity": "warning",
    "fixable": true,
    "fix": {
      "range": { "start": 142, "end": 142 },
      "replacement": "\n"
    }
  }
]

Stability

rumdl is currently Beta while its compatibility policy and 1.0 exit criteria are formalized. The core CLI, configuration model, and rule set are already intended for production use.

See Stability and Compatibility for the compatibility guarantees, versioning, deprecation, and MSRV policies, and a dateless checklist of what remains before 1.0.

If a release breaks something documented as stable, that is a bug.

Development

Prerequisites

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

Building

make build

Building for WebAssembly / WASI

The CLI can be compiled for WASI (e.g. to run under wasmtime) using the wasi feature, which excludes the host-only language server, jemalloc, and tokio stack:

rustup target add wasm32-wasip1-threads
cargo build --target wasm32-wasip1-threads --no-default-features --features wasi
# Or simply: make build-wasi

The browser/npm package uses a separate wasm feature (via wasm-bindgen) targeting wasm32-unknown-unknown:

make build-wasm
# Equivalent to: wasm-pack build --target web --no-default-features --features wasm

Always pass --no-default-features for wasm targets: the default native feature pulls in tokio and the language server, neither of which builds for wasm. Both wasm builds are exercised on every push in CI (make build-wasi / make build-wasm).

Testing

make test

JSON Schema Generation

If 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 print

The schema is automatically generated from the Rust types using schemars and should be kept in sync with the configuration structures.

Used By

rumdl is used by these notable open source projects:

Project	Stars
aio-libs/aiobotocore
apache/lucene
beeware/beeware.github.io
beeware/briefcase
beeware/toga
callowayproject/bump-my-version
chrisgrieser/nvim-scissors
chrisgrieser/nvim-spider
chrisgrieser/nvim-various-textobjs
chrisgrieser/shimmering-focus
chrisgrieser/shimmering-obsidian
copier-org/copier
DeterminateSystems/zero-to-nix
Hexlet/ru-test-assignments
kreuzberg-dev/html-to-markdown
kreuzberg-dev/kreuzberg
lra/mackup
matrix-org/matrix-rust-sdk
matrix-org/matrix.org
mikavilpas/yazi.nvim
modular/modular
mopidy/mopidy
mozilla-firefox/firefox
PyO3/pyo3
Ravencentric/awesome-arr
rust-lang/rustlings
scop/bash-completion
Ulauncher/Ulauncher
WeblateOrg/weblate
wfxr/forgit

Using rumdl? Let us know!

Sponsors

rumdl is free and open source. If it saves you time, consider sponsoring the project.

• David Hewitt

License

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