Quick Start¶

Start with a read-only check on an existing repository. This command downloads rumdl for the run, does not change files, and automatically discovers common markdownlint configuration files:

uvx rumdl check .

Compare the result before changing your configuration, editor, or CI workflow. If you already have rumdl installed, use rumdl check . instead.

Basic Usage¶

Check for issues¶

# Lint all Markdown files in current directory
rumdl check .

# Lint specific files
rumdl check README.md docs/

# Lint with verbose output
rumdl check --verbose .

Fix issues automatically¶

# Auto-fix all issues (formatter mode - exits 0 whether or not violations remain)
rumdl fmt .

# Auto-fix with violation reporting (exits 1 if unfixable issues remain)
rumdl check --fix .

Stdin/stdout formatting¶

# Format from stdin
echo "# Hello  World" | rumdl fmt --silent -

# Pipe through rumdl
cat README.md | rumdl fmt --silent - > README.fixed.md

Create a Configuration File¶

Initialize a default configuration:

# Create .rumdl.toml with defaults
rumdl init

# Create with specific preset
rumdl init --preset google

This creates a .rumdl.toml file in your current directory. rumdl can also read rumdl.toml, .config/rumdl.toml, or a [tool.rumdl] section in pyproject.toml - see Configuration Files for the full list and how rumdl picks one.

Example Configuration¶

[global]
# Exclude files/directories
exclude = ["node_modules", "vendor", ".git"]

# Set line length limit
line-length = 120

[MD013]  # Line length
line_length = 120
code_blocks = false  # Don't check code blocks

[MD033]  # No inline HTML
allowed_elements = ["br", "details", "summary"]

[MD041]  # First line heading
enabled = false  # Disable this rule

Common Workflows¶

Editor Integration¶

For real-time linting in VS Code:

rumdl vscode

Pre-commit Hook¶

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/rvben/rumdl-pre-commit
    rev: v0.2.77  # Use latest version
    hooks:
      - id: rumdl

CI/CD Pipeline¶

name: Lint Markdown
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: rvben/rumdl@v0

Understanding Output¶

rumdl outputs issues in a clear format:

docs/guide.md:1:1: [MD041] First line in file should be a level 1 heading
README.md:7:81: [MD013] Line length 97 exceeds 80 characters
README.md:10:1: [MD022] Expected 1 blank line above heading [*]

Issues: Found 3 issues in 2 files (46ms)
Run `rumdl fmt` to automatically fix 1 of the 3 issues

Each line shows:

• File path and line:column
• Rule ID in brackets (e.g., [MD022])
• Description of the issue
• [*] when rumdl fmt can fix it

Exit Codes¶

Next Steps¶

• CLI Commands - Full command reference
• Rules Reference - Explore all 88 rules
• Configuration - Advanced configuration options