rumdl Rules Reference¶

A comprehensive reference of all Markdown linting rules¶

Introduction¶

rumdl implements 66 rules for checking Markdown files. This document provides a comprehensive reference of all available rules, organized by category. Each rule has a brief description and a link to its detailed documentation.

For information on global configuration settings (file selection, rule enablement, etc.), see the Global Settings Reference.

For flavor-specific behavior (MkDocs, MDX, Quarto), see the Markdown Flavors Reference.

Rule Categories¶

• Severity Levels - Understanding Error vs Warning severities
• Heading Rules - Rules related to heading structure and formatting
• List Rules - Rules for list formatting and structure
• Whitespace Rules - Rules for spacing, indentation, and line length
• Formatting Rules - Rules for general Markdown formatting
• Code Block Rules - Rules specific to code blocks and fences
• Link and Image Rules - Rules for links, references, and images
• Table Rules - Rules for table formatting and structure
• Footnote Rules - Rules for footnote validation and formatting
• Frontmatter Rules - Rules for YAML/TOML/JSON frontmatter
• Other Rules - Miscellaneous rules that don't fit the other categories
• Opt-in Rules - Rules disabled by default

Opt-in Rules¶

The following rules are disabled by default because they enforce opinionated style choices that may not suit all projects. Enable them explicitly if your project requires these checks.

Enabling Opt-in Rules¶

.rumdl.toml:

[MD060]
enabled = true

[MD063]
enabled = true
style = "title_case"  # Optional: configure the style

[MD072]
enabled = true

pyproject.toml:

[tool.rumdl.MD060]
enabled = true

[tool.rumdl.MD063]
enabled = true
style = "title_case"

[tool.rumdl.MD072]
enabled = true

See each rule's documentation for available configuration options.

Note on Missing Rule Numbers¶

Some rule numbers are not implemented in rumdl:

• MD002 - Deprecated and removed from markdownlint v0.13.0 (replaced by MD041); removed from rumdl for compatibility
• MD006 - Not implemented in DavidAnson/markdownlint (JavaScript version); removed from rumdl for compatibility
• MD008 - Originally intended for "Unordered list spacing" but not implemented in modern markdownlint
• MD015, MD016, MD017 - These rule numbers were never assigned in either the Ruby or Node.js versions of markdownlint

These gaps in numbering are maintained for compatibility with markdownlint rule numbering.

Severity Levels¶

Rules are categorized into three severity levels based on their impact on document functionality:

Error Severity¶

Rules with Error severity flag issues that break document functionality:

• MD001 - Broken heading hierarchy prevents screen reader navigation
• MD011 - Reversed link syntax makes links non-functional
• MD024 - Duplicate headings create ID collisions, anchors point to wrong sections
• MD025 - Multiple H1 elements break document outline structure
• MD042 - Empty links have no destination and don't work
• MD045 - Missing alt text violates WCAG accessibility requirements
• MD051 - Invalid link fragments point to non-existent sections
• MD057 - Links to non-existent files are broken
• MD066 - Undefined footnote references are broken
• MD068 - Empty footnote definitions have no content

Warning Severity¶

Most rules use Warning severity by default. These flag style, formatting, and convention issues that don't break document functionality but affect readability, consistency, or best practices.

Info Severity¶

Info severity is available for rules you want to track but not treat as warnings. Useful for:

• Style issues that automatic formatting will fix
• Low-priority suggestions
• Rules you're gradually adopting

Configuring Severity¶

You can override default severities for any rule in your configuration file:

.rumdl.toml:

[MD013]
severity = "info"     # Downgrade to info (formatting will fix this)

[MD004]
severity = "error"    # Upgrade from warning to error

pyproject.toml:

[tool.rumdl.MD013]
severity = "info"

[tool.rumdl.MD004]
severity = "error"

Valid severity values: "error", "warning", "info" (case-insensitive)

Severity affects:

• Exit codes: Use --fail-on to control which severities cause exit code 1
• Output formatting: Different severities are visually distinct in console output
• LSP: Error → Error, Warning → Warning, Info → Information in your editor
• CI/CD: severity controls whether linting failures block builds

Heading Rules¶

List Rules¶

Whitespace Rules¶

Formatting Rules¶

Code Block Rules¶

Link and Image Rules¶

Table Rules¶

Footnote Rules¶

Frontmatter Rules¶

Other Rules¶

Using Rules¶

Rules can be enabled, disabled, or configured in your rumdl configuration file:

# Global configuration options
[global]
# List of rules to disable
disable = ["MD013", "MD033"]

# Rule-specific configurations
[MD003]
style = "atx"  # Heading style (atx, atx_closed, setext)

[MD004]
style = "consistent"  # List style (asterisk, plus, dash, consistent)

For more information on configuring rumdl, see the Configuration section.

Rule Severities¶

Each rule has a default severity level:

• error: Critical issues (broken links, accessibility violations)
• warning: Style and convention issues (default for most rules)
• info: Low-priority suggestions or issues that formatting will fix

You can customize rule severities in your configuration file:

[MD013]
severity = "info"  # Downgrade to info (formatting will fix this)

Use --fail-on to control which severities cause exit code 1:

• --fail-on any (default): Exit 1 on any violation
• --fail-on warning: Exit 1 on warning or error only
• --fail-on error: Exit 1 only on errors
• --fail-on never: Always exit 0

Configuration¶

You can configure rumdl using a TOML configuration file. Create a default configuration file using:

rumdl init

This generates a .rumdl.toml file with default settings that you can customize.