# rumdl - A high-performance Markdown linter, written in Rust
<div align="center">
[](https://github.com/rvben/rumdl/actions)
[](https://opensource.org/licenses/MIT)
[](https://crates.io/crates/rumdl)
[](https://pypi.org/project/rumdl/)
[](https://github.com/rvben/rumdl/releases/latest)
[](https://github.com/rvben/rumdl/stargazers)
## A modern Markdown linter and formatter, built for speed with Rust
| [**Docs**](https://github.com/rvben/rumdl/blob/main/docs/RULES.md) | [**Rules**](https://github.com/rvben/rumdl/blob/main/docs/RULES.md) | [**Configuration**](#configuration) |
</div>
## Quick Start
```bash
# Install using Cargo
cargo install rumdl
# Lint Markdown files in the current directory
rumdl check .
# Automatically fix issues
rumdl check --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. Inspired by [ruff](https://github.com/astral-sh/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 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
## Table of Contents
- [Quick Start](#quick-start)
- [Overview](#overview)
- [Installation](#installation)
- [Using Cargo (Rust)](#using-cargo-rust)
- [Using pip (Python)](#using-pip-python)
- [Using uv](#using-uv)
- [Download binary](#download-binary)
- [VS Code Extension](#vs-code-extension)
- [Usage](#usage)
- [Pre-commit Integration](#pre-commit-integration)
- [Rules](#rules)
- [Command-line Interface](#command-line-interface)
- [Commands](#commands)
- [Usage Examples](#usage-examples)
- [Configuration](#configuration)
- [Configuration File Example](#configuration-file-example)
- [Initializing Configuration](#initializing-configuration)
- [Configuration in pyproject.toml](#configuration-in-pyproject-toml)
- [Configuration Output](#configuration-output)
- [Effective Configuration (`rumdl config`)](#effective-configuration-rumdl-config)
- [Example output](#example-output)
- [Defaults Only (`rumdl config --defaults`)](#defaults-only-rumdl-config-defaults)
- [Output Style](#output-style)
- [Output Format](#output-format)
- [Development](#development)
- [Prerequisites](#prerequisites)
- [Building](#building)
- [Testing](#testing)
- [License](#license)
## Installation
Choose the installation method that works best for you:
### Using Cargo (Rust)
```bash
cargo install rumdl
```
### Using pip (Python)
```bash
pip install rumdl
```
### Using uv
For faster installation and better dependency management with [uv](https://github.com/astral-sh/uv):
```bash
# Install directly
uv tool install rumdl
# Or run without installing
uv tool run rumdl check .
```
### Download binary
```bash
# 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"
```
### VS Code Extension
For the best development experience, install the rumdl VS Code extension directly from the command line:
```bash
# Install the VS Code extension
rumdl vscode
# Check if the extension is installed
rumdl vscode --status
# Force reinstall the extension
rumdl vscode --force
```
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](https://github.com/rvben/rumdl/blob/main/docs/vscode-extension.md) for more details.
## Usage
Getting started with rumdl is simple:
```bash
# Lint a single file
rumdl check README.md
# Lint all Markdown files in current directory and subdirectories
rumdl check .
# Automatically fix issues
rumdl check --fix README.md
# Create a default configuration file
rumdl init
```
Common usage examples:
```bash
# 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" .
# 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 .
```
## Pre-commit Integration
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](https://github.com/rvben/rumdl-pre-commit)
Add the following to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/rvben/rumdl-pre-commit
rev: v0.0.45 # Use the latest release tag
hooks:
- id: rumdl
# To only check (default):
# args: []
# To automatically fix issues:
# args: [--fix]
```
- 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.
## Rules
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](https://github.com/rvben/rumdl/blob/main/docs/RULES.md) or run:
```bash
rumdl --list-rules
```
## Command-line Interface
```bash
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
- `-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)
- `-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
#### `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/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
#### `config [OPTIONS] [COMMAND]`
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
#### `server [OPTIONS]`
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
#### `vscode [OPTIONS]`
Install the rumdl VS Code extension
**Options:**
- `--force`: Force reinstall even if already installed
- `--status`: Show installation status without installing
#### `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
### Exit Codes
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).
### Usage Examples
```bash
# Lint all Markdown files in the current directory
rumdl check .
# Automatically fix issues
rumdl check --fix .
# 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 version
```
## 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
4. **Automatic markdownlint compatibility**: rumdl automatically discovers and loads existing markdownlint config files (`.markdownlint.json`, `.markdownlint.yaml`, etc.)
### Markdownlint Migration
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:
```bash
# 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](docs/global-settings.md).
### Configuration File Example
Here's an example `.rumdl.toml` configuration file:
```toml
# 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:
```bash
# 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:
```toml
[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.
### 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
```text
[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 `--defaults` flag prints only the default configuration as TOML, suitable for copy-paste or reference:
```toml
[global]
enable = []
disable = []
exclude = []
include = []
respect_gitignore = true
[MD013]
line_length = 80
code_blocks = true
...
```
## Output Style
rumdl produces clean, colorized output similar to modern linting tools:
```text
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:
```text
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:
```text
✓ 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
#### Text Output (Default)
rumdl uses a consistent output format for all issues:
```text
{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 json`:
```bash
rumdl check --output json README.md
```
This produces structured JSON output:
```json
{
"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"
}
]
}
]
}
```
## Development
### Prerequisites
- Rust 1.70 or higher
- Make (for development commands)
### Building
```bash
make build
```
### Testing
```bash
make test
```
## License
rumdl is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/rvben/rumdl",
"name": "rumdl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "markdown, linter, markdown-linter, static-analysis, documentation",
"author": "Ruben J. Jongejan <ruben.jongejan@gmail.com>",
"author_email": "\"Ruben J. Jongejan\" <ruben.jongejan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c9/3d/7dbf17a966b97e0d8bfaf3a47bed6e5d5e159877af844bc75c5045d96112/rumdl-0.0.96.tar.gz",
"platform": null,
"description": "# rumdl - A high-performance Markdown linter, written in Rust\n\n<div align=\"center\">\n\n\n\n[](https://github.com/rvben/rumdl/actions)\n[](https://opensource.org/licenses/MIT)\n[](https://crates.io/crates/rumdl)\n[](https://pypi.org/project/rumdl/)\n[](https://github.com/rvben/rumdl/releases/latest)\n[](https://github.com/rvben/rumdl/stargazers)\n\n## A modern Markdown linter and formatter, built for speed with Rust\n\n| [**Docs**](https://github.com/rvben/rumdl/blob/main/docs/RULES.md) | [**Rules**](https://github.com/rvben/rumdl/blob/main/docs/RULES.md) | [**Configuration**](#configuration) |\n\n</div>\n\n## Quick Start\n\n```bash\n# Install using Cargo\ncargo install rumdl\n\n# Lint Markdown files in the current directory\nrumdl check .\n\n# Automatically fix issues\nrumdl check --fix .\n\n# Create a default configuration file\nrumdl init\n```\n\n## Overview\n\nrumdl is a high-performance Markdown linter and fixer that helps ensure consistency and best practices\nin your Markdown files. Inspired by [ruff](https://github.com/astral-sh/ruff)'s approach to Python linting,\nrumdl brings similar speed and developer experience improvements to the Markdown ecosystem.\n\nIt offers:\n\n- \u26a1\ufe0f **Built for speed** with Rust - significantly faster than alternatives\n- \ud83d\udd0d **54 lint rules** covering common Markdown issues\n- \ud83d\udee0\ufe0f **Automatic fixing** with `--fix` for most rules\n- \ud83d\udce6 **Zero dependencies** - single binary with no runtime requirements\n- \ud83d\udd27 **Highly configurable** with TOML-based config files\n- \ud83c\udf10 **Multiple installation options** - Rust, Python, standalone binaries\n- \ud83d\udc0d **Installable via pip** for Python users\n- \ud83d\udccf **Modern CLI** with detailed error reporting\n- \ud83d\udd04 **CI/CD friendly** with non-zero exit code on errors\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Overview](#overview)\n- [Installation](#installation)\n - [Using Cargo (Rust)](#using-cargo-rust)\n - [Using pip (Python)](#using-pip-python)\n - [Using uv](#using-uv)\n - [Download binary](#download-binary)\n - [VS Code Extension](#vs-code-extension)\n- [Usage](#usage)\n- [Pre-commit Integration](#pre-commit-integration)\n- [Rules](#rules)\n- [Command-line Interface](#command-line-interface)\n - [Commands](#commands)\n - [Usage Examples](#usage-examples)\n- [Configuration](#configuration)\n - [Configuration File Example](#configuration-file-example)\n - [Initializing Configuration](#initializing-configuration)\n - [Configuration in pyproject.toml](#configuration-in-pyproject-toml)\n - [Configuration Output](#configuration-output)\n - [Effective Configuration (`rumdl config`)](#effective-configuration-rumdl-config)\n - [Example output](#example-output)\n - [Defaults Only (`rumdl config --defaults`)](#defaults-only-rumdl-config-defaults)\n- [Output Style](#output-style)\n - [Output Format](#output-format)\n- [Development](#development)\n - [Prerequisites](#prerequisites)\n - [Building](#building)\n - [Testing](#testing)\n- [License](#license)\n\n## Installation\n\nChoose the installation method that works best for you:\n\n### Using Cargo (Rust)\n\n```bash\ncargo install rumdl\n```\n\n### Using pip (Python)\n\n```bash\npip install rumdl\n```\n\n### Using uv\n\nFor faster installation and better dependency management with [uv](https://github.com/astral-sh/uv):\n\n```bash\n# Install directly\nuv tool install rumdl\n\n# Or run without installing\nuv tool run rumdl check .\n```\n\n### Download binary\n\n```bash\n# Linux/macOS\ncurl -LsSf https://github.com/rvben/rumdl/releases/latest/download/rumdl-linux-x86_64.tar.gz | tar xzf - -C /usr/local/bin\n\n# Windows PowerShell\nInvoke-WebRequest -Uri \"https://github.com/rvben/rumdl/releases/latest/download/rumdl-windows-x86_64.zip\" -OutFile \"rumdl.zip\"\nExpand-Archive -Path \"rumdl.zip\" -DestinationPath \"$env:USERPROFILE\\.rumdl\"\n```\n\n### VS Code Extension\n\nFor the best development experience, install the rumdl VS Code extension directly from the command line:\n\n```bash\n# Install the VS Code extension\nrumdl vscode\n\n# Check if the extension is installed\nrumdl vscode --status\n\n# Force reinstall the extension\nrumdl vscode --force\n```\n\nThe extension provides:\n\n- \ud83d\udd0d Real-time linting as you type\n- \ud83d\udca1 Quick fixes for common issues\n- \ud83c\udfa8 Code formatting on save\n- \ud83d\udccb Hover tooltips with rule documentation\n- \u26a1 Lightning-fast performance with zero lag\n\nThe CLI will automatically detect VS Code, Cursor, or Windsurf and install the appropriate extension. See the [VS Code extension documentation](https://github.com/rvben/rumdl/blob/main/docs/vscode-extension.md) for more details.\n\n## Usage\n\nGetting started with rumdl is simple:\n\n```bash\n# Lint a single file\nrumdl check README.md\n\n# Lint all Markdown files in current directory and subdirectories\nrumdl check .\n\n# Automatically fix issues\nrumdl check --fix README.md\n\n# Create a default configuration file\nrumdl init\n```\n\nCommon usage examples:\n\n```bash\n# Lint with custom configuration\nrumdl check --config my-config.toml docs/\n\n# Disable specific rules\nrumdl check --disable MD013,MD033 README.md\n\n# Enable only specific rules\nrumdl check --enable MD001,MD003 README.md\n\n# Exclude specific files/directories\nrumdl check --exclude \"node_modules,dist\" .\n\n# Include only specific files/directories\nrumdl check --include \"docs/*.md,README.md\" .\n\n# Combine include and exclude patterns\nrumdl check --include \"docs/**/*.md\" --exclude \"docs/temp,docs/drafts\" .\n\n# Don't respect gitignore files (note: --respect-gitignore defaults to true)\nrumdl check --respect-gitignore=false .\n```\n\n## Pre-commit Integration\n\nYou can use `rumdl` as a pre-commit hook to check and fix your Markdown files.\n\nThe recommended way is to use the official pre-commit hook repository:\n\n[rumdl-pre-commit repository](https://github.com/rvben/rumdl-pre-commit)\n\nAdd the following to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/rvben/rumdl-pre-commit\n rev: v0.0.45 # Use the latest release tag\n hooks:\n - id: rumdl\n # To only check (default):\n # args: []\n # To automatically fix issues:\n # args: [--fix]\n```\n\n- By default, the hook will only check for issues.\n- To automatically fix issues, add `args: [--fix]` to the hook configuration.\n\nWhen 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.\n\n## Rules\n\nrumdl implements 54 lint rules for Markdown files. Here are some key rule categories:\n\n| Category | Description | Example Rules |\n|-----------|-------------|---------------|\n| **Headings** | Proper heading structure and formatting | MD001, MD002, MD003 |\n| **Lists** | Consistent list formatting and structure | MD004, MD005, MD007 |\n| **Whitespace** | Proper spacing and line length | MD009, MD010, MD012 |\n| **Code** | Code block formatting and language tags | MD040, MD046, MD048 |\n| **Links** | Proper link and reference formatting | MD034, MD039, MD042 |\n| **Images** | Image alt text and references | MD045, MD052 |\n| **Style** | Consistent style across document | MD031, MD032, MD035 |\n\nFor a complete list of rules and their descriptions, see our [documentation](https://github.com/rvben/rumdl/blob/main/docs/RULES.md) or run:\n\n```bash\nrumdl --list-rules\n```\n\n## Command-line Interface\n\n```bash\nrumdl <command> [options] [file or directory...]\n```\n\n### Commands\n\n#### `check [PATHS...]`\n\nLint Markdown files and print warnings/errors (main subcommand)\n\n**Arguments:**\n\n- `[PATHS...]`: Files or directories to lint. If provided, these paths take precedence over include patterns\n\n**Options:**\n\n- `-f, --fix`: Automatically fix issues where possible\n- `-l, --list-rules`: List all available rules\n- `-d, --disable <rules>`: Disable specific rules (comma-separated)\n- `-e, --enable <rules>`: Enable only specific rules (comma-separated)\n- `--exclude <patterns>`: Exclude specific files or directories (comma-separated glob patterns)\n- `--include <patterns>`: Include only specific files or directories (comma-separated glob patterns)\n- `--respect-gitignore`: Respect .gitignore files when scanning directories (does not apply to explicitly provided paths)\n- `-v, --verbose`: Show detailed output\n- `--profile`: Show profiling information\n- `--statistics`: Show rule violation statistics summary\n- `-q, --quiet`: Quiet mode\n- `-o, --output <format>`: Output format: `text` (default) or `json`\n- `--stdin`: Read from stdin instead of files\n\n#### `init [OPTIONS]`\n\nCreate a default configuration file in the current directory\n\n**Options:**\n\n- `--pyproject`: Generate configuration for `pyproject.toml` instead of `.rumdl.toml`\n\n#### `import <FILE> [OPTIONS]`\n\nImport and convert markdownlint configuration files to rumdl format\n\n**Arguments:**\n\n- `<FILE>`: Path to markdownlint config file (JSON/YAML)\n\n**Options:**\n\n- `-o, --output <path>`: Output file path (default: `.rumdl.toml`)\n- `--format <format>`: Output format: `toml` or `json` (default: `toml`)\n- `--dry-run`: Show converted config without writing to file\n\n#### `rule [<rule>]`\n\nShow information about a rule or list all rules\n\n**Arguments:**\n\n- `[rule]`: Rule name or ID (optional). If provided, shows details for that rule. If omitted, lists all available rules\n\n#### `config [OPTIONS] [COMMAND]`\n\nShow configuration or query a specific key\n\n**Options:**\n\n- `--defaults`: Show only the default configuration values\n- `--output <format>`: Output format (e.g. `toml`, `json`)\n\n**Subcommands:**\n\n- `get <key>`: Query a specific config key (e.g. `global.exclude` or `MD013.line_length`)\n- `file`: Show the absolute path of the configuration file that was loaded\n\n#### `server [OPTIONS]`\n\nStart the Language Server Protocol server for editor integration\n\n**Options:**\n\n- `--port <PORT>`: TCP port to listen on (for debugging)\n- `--stdio`: Use stdio for communication (default)\n- `-v, --verbose`: Enable verbose logging\n\n#### `vscode [OPTIONS]`\n\nInstall the rumdl VS Code extension\n\n**Options:**\n\n- `--force`: Force reinstall even if already installed\n- `--status`: Show installation status without installing\n\n#### `version`\n\nShow version information\n\n### Global Options\n\nThese options are available for all commands:\n\n- `--color <mode>`: Control colored output: `auto` (default), `always`, `never`\n- `--config <file>`: Path to configuration file\n- `--no-config`: Ignore all configuration files and use built-in defaults\n\n### Exit Codes\n\nrumdl uses exit codes following Ruff's convention for easy CI/CD integration:\n\n- `0`: Success - no issues found\n- `1`: Linting violations found\n- `2`: Tool error (configuration error, file access error, invalid arguments, etc.)\n\nThis 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).\n\n### Usage Examples\n\n```bash\n# Lint all Markdown files in the current directory\nrumdl check .\n\n# Automatically fix issues\nrumdl check --fix .\n\n# Create a default configuration file\nrumdl init\n\n# Create or update a pyproject.toml file with rumdl configuration\nrumdl init --pyproject\n\n# Import a markdownlint config file\nrumdl import .markdownlint.json\n\n# Convert markdownlint config to JSON format\nrumdl import --format json .markdownlint.yaml --output rumdl-config.json\n\n# Preview conversion without writing file\nrumdl import --dry-run .markdownlint.json\n\n# Show information about a specific rule\nrumdl rule MD013\n\n# List all available rules\nrumdl rule\n\n# Query a specific config key\nrumdl config get global.exclude\n\n# Show the path of the loaded configuration file\nrumdl config file\n\n# Show configuration as JSON instead of the default format\nrumdl config --output json\n\n# Lint content from stdin\necho \"# My Heading\" | rumdl check --stdin\n\n# Get JSON output for integration with other tools\nrumdl check --output json README.md\n\n# Show statistics summary of rule violations\nrumdl check --statistics .\n\n# Disable colors in output\nrumdl check --color never README.md\n\n# Use built-in defaults, ignoring all config files\nrumdl check --no-config README.md\n\n# Show version information\nrumdl version\n```\n\n## Configuration\n\nrumdl can be configured in several ways:\n\n1. Using a `.rumdl.toml` file in your project directory\n2. Using the `[tool.rumdl]` section in your project's `pyproject.toml` file (for Python projects)\n3. Using command-line arguments\n4. **Automatic markdownlint compatibility**: rumdl automatically discovers and loads existing markdownlint config files (`.markdownlint.json`, `.markdownlint.yaml`, etc.)\n\n### Markdownlint Migration\n\nrumdl provides seamless compatibility with existing markdownlint configurations:\n\n**Automatic Discovery**: rumdl automatically detects and loads markdownlint config files:\n\n- `.markdownlint.json` / `.markdownlint.jsonc`\n- `.markdownlint.yaml` / `.markdownlint.yml`\n- `markdownlint.json` / `markdownlint.yaml`\n\n**Explicit Import**: Convert markdownlint configs to rumdl format:\n\n```bash\n# Convert to .rumdl.toml\nrumdl import .markdownlint.json\n\n# Convert to JSON format\nrumdl import --format json .markdownlint.yaml --output config.json\n\n# Preview conversion\nrumdl import --dry-run .markdownlint.json\n```\n\nFor comprehensive documentation on global settings (file selection, rule enablement, etc.), see our [Global Settings Reference](docs/global-settings.md).\n\n### Configuration File Example\n\nHere's an example `.rumdl.toml` configuration file:\n\n```toml\n# Global settings\nline-length = 100\nexclude = [\"node_modules\", \"build\", \"dist\"]\nrespect-gitignore = true\n\n# Disable specific rules\ndisabled-rules = [\"MD013\", \"MD033\"]\n\n# Configure individual rules\n[MD007]\nindent = 2\n\n[MD013]\nline-length = 100\ncode-blocks = false\ntables = false\n\n[MD025]\nlevel = 1\nfront-matter-title = \"title\"\n\n[MD044]\nnames = [\"rumdl\", \"Markdown\", \"GitHub\"]\n\n[MD048]\ncode-fence-style = \"backtick\"\n```\n\n### Initializing Configuration\n\nTo create a configuration file, use the `init` command:\n\n```bash\n# Create a .rumdl.toml file (for any project)\nrumdl init\n\n# Create or update a pyproject.toml file with rumdl configuration (for Python projects)\nrumdl init --pyproject\n```\n\n### Configuration in pyproject.toml\n\nFor Python projects, you can include rumdl configuration in your `pyproject.toml` file, keeping all project configuration in one place. Example:\n\n```toml\n[tool.rumdl]\n# Global options at root level\nline-length = 100\ndisable = [\"MD033\"]\ninclude = [\"docs/*.md\", \"README.md\"]\nexclude = [\".git\", \"node_modules\"]\nignore-gitignore = false\n\n# Rule-specific configuration\n[tool.rumdl.MD013]\ncode_blocks = false\ntables = false\n\n[tool.rumdl.MD044]\nnames = [\"rumdl\", \"Markdown\", \"GitHub\"]\n```\n\nBoth kebab-case (`line-length`, `ignore-gitignore`) and snake_case (`line_length`, `ignore_gitignore`) formats are supported for compatibility with different Python tooling conventions.\n\n### Configuration Output\n\n#### Effective Configuration (`rumdl config`)\n\nThe `rumdl config` command prints the **full effective configuration** (defaults + all overrides), showing every key and its value, annotated with the source of each value.\nThe output is colorized and the `[from ...]` annotation is globally aligned for easy scanning.\n\n#### Example output\n\n```text\n[global]\n enable = [] [from default]\n disable = [\"MD033\"] [from .rumdl.toml]\n include = [\"README.md\"] [from .rumdl.toml]\n respect_gitignore = true [from .rumdl.toml]\n\n[MD013]\n line_length = 200 [from .rumdl.toml]\n code_blocks = true [from .rumdl.toml]\n ...\n```\n\n- **Keys** are cyan, **values** are yellow, and the `[from ...]` annotation is colored by source:\n - Green: CLI\n - Blue: `.rumdl.toml`\n - Magenta: `pyproject.toml`\n - Yellow: default\n- The `[from ...]` column is aligned across all sections.\n\n### Defaults Only (`rumdl config --defaults`)\n\nThe `--defaults` flag prints only the default configuration as TOML, suitable for copy-paste or reference:\n\n```toml\n[global]\nenable = []\ndisable = []\nexclude = []\ninclude = []\nrespect_gitignore = true\n\n[MD013]\nline_length = 80\ncode_blocks = true\n...\n```\n\n## Output Style\n\nrumdl produces clean, colorized output similar to modern linting tools:\n\n```text\nREADME.md:12:1: [MD022] Headings should be surrounded by blank lines [*]\nREADME.md:24:5: [MD037] Spaces inside emphasis markers: \"* incorrect *\" [*]\nREADME.md:31:76: [MD013] Line length exceeds 80 characters\nREADME.md:42:3: [MD010] Hard tabs found, use spaces instead [*]\n```\n\nWhen running with `--fix`, rumdl shows which issues were fixed:\n\n```text\nREADME.md:12:1: [MD022] Headings should be surrounded by blank lines [fixed]\nREADME.md:24:5: [MD037] Spaces inside emphasis markers: \"* incorrect *\" [fixed]\nREADME.md:42:3: [MD010] Hard tabs found, use spaces instead [fixed]\n\nFixed 3 issues in 1 file\n```\n\nFor a more detailed view, use the `--verbose` option:\n\n```text\n\u2713 No issues found in CONTRIBUTING.md\nREADME.md:12:1: [MD022] Headings should be surrounded by blank lines [*]\nREADME.md:24:5: [MD037] Spaces inside emphasis markers: \"* incorrect *\" [*]\nREADME.md:42:3: [MD010] Hard tabs found, use spaces instead [*]\n\nFound 3 issues in 1 file (2 files checked)\nRun with `--fix` to automatically fix issues\n```\n\n### Output Format\n\n#### Text Output (Default)\n\nrumdl uses a consistent output format for all issues:\n\n```text\n{file}:{line}:{column}: [{rule_id}] {message} [{fix_indicator}]\n```\n\nThe output is colorized by default:\n\n- Filenames appear in blue and underlined\n- Line and column numbers appear in cyan\n- Rule IDs appear in yellow\n- Error messages appear in white\n- Fixable issues are marked with `[*]` in green\n- Fixed issues are marked with `[fixed]` in green\n\n#### JSON Output\n\nFor integration with other tools and automation, use `--output json`:\n\n```bash\nrumdl check --output json README.md\n```\n\nThis produces structured JSON output:\n\n```json\n{\n \"summary\": {\n \"total_files\": 1,\n \"files_with_issues\": 1,\n \"total_issues\": 2,\n \"fixable_issues\": 1\n },\n \"files\": [\n {\n \"path\": \"README.md\",\n \"issues\": [\n {\n \"line\": 12,\n \"column\": 1,\n \"rule\": \"MD022\",\n \"message\": \"Headings should be surrounded by blank lines\",\n \"fixable\": true,\n \"severity\": \"error\"\n }\n ]\n }\n ]\n}\n```\n\n## Development\n\n### Prerequisites\n\n- Rust 1.70 or higher\n- Make (for development commands)\n\n### Building\n\n```bash\nmake build\n```\n\n### Testing\n\n```bash\nmake test\n```\n\n## License\n\nrumdl is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fast Markdown linter written in Rust",
"version": "0.0.96",
"project_urls": {
"Homepage": "https://github.com/rvben/rumdl",
"Repository": "https://github.com/rvben/rumdl.git"
},
"split_keywords": [
"markdown",
" linter",
" markdown-linter",
" static-analysis",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1b2b281f294cdfd2053fbdb44f927ffdcb7d46bfdac95226c37b946409bf56a9",
"md5": "fb534d3926000af5350cd2fcb58539d8",
"sha256": "44f16fb023d7bacc40cd24d7fc91de9ce43dbb5cf211dc46c1446d7a4be00675"
},
"downloads": -1,
"filename": "rumdl-0.0.96-py3-none-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "fb534d3926000af5350cd2fcb58539d8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6126556,
"upload_time": "2025-07-16T10:21:41",
"upload_time_iso_8601": "2025-07-16T10:21:41.478722Z",
"url": "https://files.pythonhosted.org/packages/1b/2b/281f294cdfd2053fbdb44f927ffdcb7d46bfdac95226c37b946409bf56a9/rumdl-0.0.96-py3-none-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "841a3d659711b7a18f6df73a900dcd5bbb867a3f2afc13d9d1005e25011f5410",
"md5": "fca711ce7b5288be20816aebeb0aebdf",
"sha256": "a4abadf89f8c57253d61fce7bd23517cc251574bc8c09fa7b1d0aa32d4050a4d"
},
"downloads": -1,
"filename": "rumdl-0.0.96-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "fca711ce7b5288be20816aebeb0aebdf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5904104,
"upload_time": "2025-07-16T10:21:37",
"upload_time_iso_8601": "2025-07-16T10:21:37.783441Z",
"url": "https://files.pythonhosted.org/packages/84/1a/3d659711b7a18f6df73a900dcd5bbb867a3f2afc13d9d1005e25011f5410/rumdl-0.0.96-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5145b37125f352014e86d850f18e261a225a08fc8e137dc66080f4b110225610",
"md5": "437f6ea3d5873e8e5a2a759b72bd7097",
"sha256": "2583708270fa739549506b3870337beb10c3c65aec66195f8e4f429217e6d778"
},
"downloads": -1,
"filename": "rumdl-0.0.96-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "437f6ea3d5873e8e5a2a759b72bd7097",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6501133,
"upload_time": "2025-07-16T10:21:39",
"upload_time_iso_8601": "2025-07-16T10:21:39.766824Z",
"url": "https://files.pythonhosted.org/packages/51/45/b37125f352014e86d850f18e261a225a08fc8e137dc66080f4b110225610/rumdl-0.0.96-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "02b58de51c5d0f5bc49c11d6b89aa5d864f8db5e8ddd77a3a8d9c5ac8e99feed",
"md5": "9db83074e6d695d54f5228212c3aa371",
"sha256": "ec7d6df52a1a3031e32e6aae623e4090f374b189371e7edd7f989d83ead8b636"
},
"downloads": -1,
"filename": "rumdl-0.0.96-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "9db83074e6d695d54f5228212c3aa371",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6748327,
"upload_time": "2025-07-16T10:21:44",
"upload_time_iso_8601": "2025-07-16T10:21:44.480729Z",
"url": "https://files.pythonhosted.org/packages/02/b5/8de51c5d0f5bc49c11d6b89aa5d864f8db5e8ddd77a3a8d9c5ac8e99feed/rumdl-0.0.96-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f2ee79d3955be091b60b79af464111452aea0e2fa234a7dd43b7bc35398c8d97",
"md5": "dfddbea75ae1a558aa90dbdeb6a50b9e",
"sha256": "12da451f2d28fdb52749e373d9abc1e76cc4f81cb2d6185d30d50487d45ff0dc"
},
"downloads": -1,
"filename": "rumdl-0.0.96-py3-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "dfddbea75ae1a558aa90dbdeb6a50b9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6052240,
"upload_time": "2025-07-16T10:21:42",
"upload_time_iso_8601": "2025-07-16T10:21:42.766338Z",
"url": "https://files.pythonhosted.org/packages/f2/ee/79d3955be091b60b79af464111452aea0e2fa234a7dd43b7bc35398c8d97/rumdl-0.0.96-py3-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c93d7dbf17a966b97e0d8bfaf3a47bed6e5d5e159877af844bc75c5045d96112",
"md5": "027880836bb6a3f810684a14da34a4bb",
"sha256": "88d413aa969e564b699315cad797b811aa255743ded3e973c9a5979bd3a8b71a"
},
"downloads": -1,
"filename": "rumdl-0.0.96.tar.gz",
"has_sig": false,
"md5_digest": "027880836bb6a3f810684a14da34a4bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 722561,
"upload_time": "2025-07-16T10:21:45",
"upload_time_iso_8601": "2025-07-16T10:21:45.675473Z",
"url": "https://files.pythonhosted.org/packages/c9/3d/7dbf17a966b97e0d8bfaf3a47bed6e5d5e159877af844bc75c5045d96112/rumdl-0.0.96.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 10:21:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rvben",
"github_project": "rumdl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rumdl"
}
JSON
