Rumdl: A Markdown Linter Written in Rust

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.

It offers:

• ⚡️ Built for speed with Rust - significantly faster than alternatives
• 🔍 54 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 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 - 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
    • Using Homebrew (macOS/Linux)
    • Using Cargo (Rust)
    • Using pip (Python)
    • Using uv
    • Download binary
    • VS Code Extension
  • Usage
    • Stdin/Stdout Formatting
    • Editor Integration
  • Pre-commit Integration
    • Excluding Files in Pre-commit
  • CI/CD Integration
    • GitHub Actions
  • Rules
  • Command-line Interface
    • Commands
      • check [PATHS...]
      • fmt [PATHS...]
      • init [OPTIONS]
      • import <FILE> [OPTIONS]
      • rule [<rule>]
      • config [OPTIONS] [COMMAND]
      • server [OPTIONS]
      • vscode [OPTIONS]
      • version
    • Global Options
    • Exit Codes
    • Usage Examples
  • Configuration
    • Configuration Discovery
    • Editor Support (JSON Schema)
    • Global Configuration
    • Markdownlint Migration
    • Inline Configuration
    • Configuration File Example
    • Initializing Configuration
    • Configuration in pyproject.toml
    • Configuration Output
      • Effective Configuration (rumdl config)
      • Example output
    • Defaults Only (rumdl config --defaults)
  • Output Style
    • Output Format
      • Text Output (Default)
      • JSON Output
  • Development
    • Prerequisites
    • Building
    • Testing
    • JSON Schema Generation
  • License

Choose the installation method that works best for you:

For faster installation and better dependency management with uv:

For the best development experience, install the rumdl VS Code extension directly from the command line:

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

Common usage examples:

rumdl supports formatting via stdin/stdout, making it ideal for editor integrations and CI pipelines:

For editor integration, use stdin/stdout mode with the --quiet flag to suppress diagnostic messages:

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:

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

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:

1. Use force_exclude in your configuration file:

   # .rumdl.toml [global] exclude = ["generated/*.md", "vendor/**"] force_exclude = true # Enforce excludes even for explicitly provided files

2. Use the --force-exclude flag in your pre-commit config:

   repos: - repo: https://github.com/rvben/rumdl-pre-commit rev: v0.0.99 hooks: - id: rumdl args: [--force-exclude] # Respect exclude patterns from config

rumdl can output annotations directly in GitHub Actions format, making issues appear inline in pull requests:

This produces annotations that GitHub automatically displays in the PR's "Files changed" tab. Supports error/warning severity levels and precise issue locations.

rumdl implements 54 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:

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) or json
• --stdin: Read from stdin instead of files

Format Markdown files (alias for check --fix)

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:

Create a default configuration file in the current directory

Options:

• --pyproject: Generate configuration for pyproject.toml instead 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: toml or json (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.exclude or MD013.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

rumdl uses exit codes following Ruff's convention for easy CI/CD integration:

• 0: Success - no issues found
• 1: Linting violations found
• 2: Tool error (configuration error, file access error, invalid arguments, etc.)

This allows scripts and CI/CD systems to distinguish between "the tool found problems in your files" (exit 1) and "the tool couldn't run properly" (exit 2).

rumdl can be configured in several ways:

1. Using a .rumdl.toml file in your project directory or parent directories
2. Using the [tool.rumdl] section in your project's pyproject.toml file (for Python projects)
3. Using command-line arguments
4. 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, or pyproject.toml (with [tool.rumdl] section)
• Stops at the first configuration file found
• Stops searching when it encounters a .git directory (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:

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:

1. Install the "Even Better TOML" extension
2. The schema will be automatically associated with .rumdl.toml and rumdl.toml files once submitted to SchemaStore

Manual Schema Association:

Add this to your .rumdl.toml file (in a comment, as TOML doesn't support $schema):

This 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/ (respects XDG_CONFIG_HOME if set)
• Windows: %APPDATA%\rumdl\

Files checked (in order):

1. .rumdl.toml
2. rumdl.toml
3. pyproject.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:

Note: 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.yml
• markdownlint.json / markdownlint.yaml

** Explicit Import**: Convert markdownlint configs to rumdl format:

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

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:

To create a configuration file, use the init command:

For Python projects, you can include rumdl configuration in your pyproject.toml file, keeping all project configuration in one place. Example:

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.

• ** 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:

rumdl produces clean, colorized output similar to modern linting tools:

When running with --fix, rumdl shows which issues were fixed:

For a more detailed view, use the --verbose option:

rumdl uses a consistent output format for all issues:

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:

This produces structured JSON output:

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

If you modify the configuration structures in src/config.rs, regenerate the JSON schema:

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