Comparison with markdownlint¶

This document provides a detailed comparison between rumdl and markdownlint, covering rule compatibility, intentional design differences, and features unique to each tool.

Quick Summary¶

rumdl offers high markdownlint compatibility with intentional differences while also adding performance improvements and newer features. All 53 markdownlint rules are implemented, but rumdl prefers predictable CommonMark-oriented behavior over bug-for-bug compatibility in a few documented areas.

Key Differences:

• Performance: rumdl is significantly faster (30-100x in many cases) thanks to Rust and intelligent caching
• Rule Coverage: All 53 markdownlint rules are implemented, with a small number of intentional behavioral differences documented below
• Unique Features: 18 additional rules (MD057, MD061-MD077), built-in LSP server, VS Code extension, 6 Markdown flavors
• Configuration: Automatic markdownlint config discovery and conversion

Rule Coverage¶

Implemented Rules¶

rumdl implements 71 rules total: all 53 markdownlint rules plus 18 unique rules.

Markdownlint-compatible rules (53): All markdownlint rules are implemented with full compatibility. See the Rules Reference for the complete list.

Note: Rule numbers MD001-MD060 have gaps (MD002, MD006, MD008, MD015-MD017 were never implemented in markdownlint). rumdl maintains these gaps for compatibility.

Rules Unique to rumdl¶

rumdl implements 18 additional rules not found in markdownlint:

Opt-in rules: MD060, MD063, MD070, MD072, MD073, and MD074 are disabled by default. Enable them explicitly in your configuration.

Intentional Design Differences¶

1. CommonMark Specification Compliance¶

rumdl prioritizes CommonMark specification compliance over bug-for-bug compatibility with markdownlint's parsing.

Example - List Continuation vs Code Blocks:

1. List item

    This is a continuation paragraph (4 spaces = continuation)

        This is a code block (8 spaces = continuation indent + 4)

• markdownlint: May incorrectly treat 4-space indented paragraphs as code blocks
• rumdl: Follows CommonMark: 4 spaces = list continuation, 8 spaces = code block within list
• Rationale: Reduces false positives and aligns with the official Markdown spec

References:

• CommonMark List Specification
• rumdl Issue #128 - False positive fix

2. Performance Architecture¶

rumdl uses Rust and intelligent caching for significant performance gains:

• Cold start: 30-100x faster than markdownlint on large repositories
• Incremental: Only re-lints changed files (Ruff-style caching)
• Parallel processing: Multi-threaded file processing and rule execution
• Zero dependencies: Single binary, no Node.js runtime required

Benchmark: See the performance comparison in the main README, which shows detailed benchmarks on the Rust Book repository (478 markdown files).

3. Auto-fix Mode Differences¶

Both tools support auto-fixing, but with different philosophies:

markdownlint:

• Fixes issues in-place
• Requires --fix flag

rumdl:

• Two modes: rumdl fmt (formatter-style, exits 0) and rumdl check --fix (linter-style, exits 0 if all violations fixed, 1 if violations remain)
• --diff mode to preview changes
• Parallel file fixing (4.8x faster on multi-file projects)

Why two modes?

• fmt: Designed for editor integration (doesn't fail on unfixable issues)
• check --fix: Designed for CI/CD (fails if violations remain after fixing)

4. Configuration Philosophy¶

Automatic Discovery:

rumdl automatically discovers and loads both markdownlint and markdownlint-cli2 config files:

# rumdl automatically finds and uses these (in precedence order):
.markdownlint-cli2.jsonc
.markdownlint-cli2.yaml
.markdownlint-cli2.yml
.markdownlint.json
.markdownlint.yaml
markdownlint.json

For markdownlint-cli2 files, rumdl extracts rule configuration from the config: key and ignores cli2-specific keys like globs and ignores.

Conversion Tool:

# Convert markdownlint config to rumdl format:
rumdl import .markdownlint.json --output .rumdl.toml

Multiple Formats:

• Native: .rumdl.toml (TOML, with JSON schema support)
• Python projects: pyproject.toml with [tool.rumdl] section
• Markdownlint: Automatic compatibility mode

5. Editor Integration¶

rumdl includes a built-in Language Server Protocol (LSP) implementation:

# Start LSP server
rumdl server

# Install VS Code extension
rumdl vscode

Features:

• Real-time linting as you type
• Quick fixes for supported rules
• Hover documentation for rules
• Zero configuration required

6. Markdown Flavors¶

rumdl supports 6 Markdown flavors to adapt rule behavior for different documentation systems:

Configuration:

[global]
flavor = "mkdocs"

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

markdownlint does not have built-in flavor support; users must configure individual rules manually.

Configuration Compatibility¶

Markdownlint Config Auto-Detection¶

rumdl automatically discovers and loads markdownlint and markdownlint-cli2 configurations:

# .markdownlint.yaml (automatically loaded)
MD013: false
MD033:
  allowed_elements: ['br', 'img']

# .markdownlint-cli2.yaml (also automatically loaded)
config:
  MD013: false
  MD033:
    allowed_elements: ['br', 'img']

Equivalent rumdl Configuration¶

# .rumdl.toml
[global]
disable = ["MD013"]

[MD033]
allowed_elements = ["br", "img"]

Configuration Mapping¶

Most markdownlint options map directly to rumdl:

Per-File Ignores¶

Both support per-file rule configuration:

# rumdl
[per-file-ignores]
"README.md" = ["MD033"]  # Allow HTML in README
"docs/api/**/*.md" = ["MD013"]  # Relax line length in API docs

markdownlint uses glob patterns in separate config files or inline comments.

Inline Configuration Compatibility¶

rumdl supports both rumdl and markdownlint inline comment styles:

<!-- markdownlint-disable MD013 -->
This line can be as long as needed
<!-- markdownlint-enable MD013 -->

<!-- rumdl-disable MD013 -->
Alternative syntax also supported
<!-- rumdl-enable MD013 -->

Both syntaxes work identically in rumdl for seamless migration.

CLI Differences¶

Command Structure¶

markdownlint:

markdownlint README.md
markdownlint --fix **/*.md
markdownlint --config .markdownlint.json docs/

rumdl:

rumdl check README.md
rumdl check --fix .  # or: rumdl fmt .
rumdl check --config .rumdl.toml docs/

Output Formats¶

Both support:

• Text output (colored, human-readable)
• JSON output (for tool integration)

rumdl additionally supports:

• Source line display with caret underlines (--output-format full)
• GitHub Actions annotations (--output-format github)
• GitLab, Azure, SARIF, JUnit, and Pylint formats
• Statistics summary (--statistics)
• Profiling information (--profile)

Exit Codes¶

markdownlint-cli:

• 0: No violations
• 1: Violations found
• 2: Unable to write output
• 3: Unable to load custom rules
• 4: Unexpected error

rumdl:

• 0: Success (or rumdl fmt completed successfully)
• 1: Violations found (or remain after --fix)
• 2: Tool error

Migration Guide¶

From markdownlint to rumdl¶

1. Install rumdl:

   bash uv tool install rumdl # or: cargo install rumdl # or: pip install rumdl # or: brew install rumdl (See README.md)

2. Test with existing config:

   bash # rumdl automatically discovers .markdownlint.json rumdl check .

3. (Optional) Convert config:

   bash rumdl import .markdownlint.json

4. Update CI/CD:

   ```yaml # Before (markdownlint) - run: markdownlint '*/.md'

# After (rumdl) - run: rumdl check . ```

Known Behavioral Differences¶

These are intentional deviations where rumdl produces different results than markdownlint. They are design decisions, not bugs.

MD004 (unordered-list-style): In consistent mode, rumdl uses prevalence-based detection (most common marker wins, ties prefer dash). markdownlint uses the first marker as the standard.

MD005/MD007 (list-indent / ul-indent): rumdl uses parent-based dynamic indentation, properly handling ordered lists with variable marker widths (e.g., 1. vs 10.). markdownlint may treat children at different indentation levels as inconsistent.

MD012 (no-multiple-blanks): rumdl uses the filtered_lines() architecture to skip frontmatter, code blocks, and flavor-specific constructs. This may produce slightly different counts near block boundaries.

MD013 (line-length): rumdl exempts entire lines that are completely unbreakable (URLs with no spaces, long code spans). It also supports line_length = 0 to mean unlimited. markdownlint exempts more selectively.

MD029 (ordered-list-prefix): rumdl uses CommonMark AST start values. A list starting at 11 expects items 11, 12, 13. rumdl only auto-fixes when start_value == 1 to preserve explicit numbering intent.

If you encounter other compatibility issues, please file an issue.

Feature Comparison Table¶

CommonMark Compliance¶

rumdl prioritizes CommonMark specification compliance to reduce false positives and align with modern Markdown standards:

Reporting Compatibility Issues¶

If you find a compatibility issue with markdownlint:

1. Check existing issues
2. Verify with both tools: markdownlint file.md and rumdl check file.md
3. File an issue with:
   • Markdown sample
   • Expected behavior (markdownlint output)
   • Actual behavior (rumdl output)
   • Versions of both tools

See Also¶

• Tool Comparison Matrix - Broad comparison of Markdown linters and formatters
• Comparison with mdformat - For users coming from the mdformat formatter

References¶

• markdownlint documentation
• CommonMark specification
• rumdl GitHub repository
• rumdl rules documentation
• rumdl flavors documentation