rumdl Rules Reference
June 25, 2026 · View on GitHub
A comprehensive reference of all Markdown linting rules
Introduction
rumdl implements 76 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.
| Rule | Description | Why opt-in |
|---|---|---|
| MD060 | Table formatting | Makes significant formatting changes to existing tables |
| MD063 | Heading capitalization | Style varies by guide (AP, Chicago, APA) |
| MD070 | Nested code fence | Auto-fix modifies document structure, false positives on docs |
| MD072 | Frontmatter key sort | Many projects prefer semantic ordering over alphabetical |
| MD073 | TOC validation | Requires specific TOC markers in document |
| MD074 | MkDocs nav validation | Requires flavor = "mkdocs" to activate |
| MD080 | Heading anchor collision | Collisions are functional under platform auto-suffixing |
| MD082 | No empty sections | Empty sections are sometimes intentional stubs |
Enabling Opt-in Rules
Use extend-enable in the [global] section to enable opt-in rules:
.rumdl.toml:
[global]
extend-enable = ["MD060", "MD063", "MD072"]
# Configure enabled rules as needed
[MD060]
style = "aligned"
[MD063]
style = "title-case"
pyproject.toml:
[tool.rumdl]
extend-enable = ["MD060", "MD063", "MD072"]
[tool.rumdl.MD060]
style = "aligned"
[tool.rumdl.MD063]
style = "title-case"
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-onto 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
| Rule ID | Rule Name | Description |
|---|---|---|
| MD001 | Heading increment | Headings should only increment by one level at a time |
| MD003 | Heading style | Heading style should be consistent |
| MD018 | No space atx | No space after hash on atx style heading |
| MD019 | Multiple space atx | Multiple spaces after hash on atx style heading |
| MD020 | No space closed atx | No space inside hashes on closed atx style heading |
| MD021 | Multiple space closed atx | Multiple spaces inside hashes on closed atx style heading |
| MD022 | Blanks around headings | Headings should be surrounded by blank lines |
| MD023 | Heading start left | Headings must start at the beginning of the line |
| MD024 | Multiple headings | Multiple headings with the same content |
| MD025 | Single title | Multiple top-level headings in the same document |
| MD036 | No emphasis as heading | Emphasis used instead of a heading |
| MD041 | First line h1 | First line in a file should be a top-level heading |
| MD043 | Required headings | Required heading structure |
| MD063 | Heading capitalization | Heading text capitalization style |
| MD080 | Heading anchor collision | Heading anchors (slugs) must be unique |
| MD082 | No empty sections | Headings must have content before the next heading |
List Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD004 | UL style | Unordered list style |
| MD005 | List indent | Inconsistent indentation for list items at the same level |
| MD007 | UL indent | Unordered list indentation |
| MD029 | OL prefix | Ordered list item prefix |
| MD030 | List marker space | Spaces after list markers |
| MD032 | Blanks around lists | Lists should be surrounded by blank lines |
| MD069 | No duplicate list markers | Duplicate markers like - - text from copy-paste |
| MD076 | List item spacing | List item spacing should be consistent |
| MD077 | List continuation indent | List continuation content indentation |
Whitespace Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD009 | No trailing spaces | No trailing spaces |
| MD010 | No hard tabs | No hard tabs |
| MD012 | No multiple blanks | No multiple consecutive blank lines |
| MD013 | Line length | Line length |
| MD027 | Multiple spaces blockquote | Multiple spaces after blockquote symbol |
| MD028 | Blanks blockquote | Blank line inside blockquote |
| MD031 | Blanks around fences | Fenced code blocks should be surrounded by blank lines |
| MD047 | File end newline | Files should end with a single newline character |
| MD064 | No multiple consecutive spaces | Multiple consecutive spaces in content |
| MD065 | Blanks around HR | Horizontal rules should be surrounded by blank lines |
Formatting Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD026 | No trailing punctuation | Trailing punctuation in heading |
| MD033 | No inline HTML | Inline HTML |
| MD035 | HR style | Horizontal rule style |
| MD037 | Spaces around emphasis | Spaces inside emphasis markers |
| MD038 | No space in code | Spaces inside code span elements |
| MD039 | No space in links | Spaces inside link text |
| MD044 | Proper names | Proper names should have consistent capitalization |
| MD049 | Emphasis style | Emphasis style should be consistent |
| MD050 | Strong style | Strong style should be consistent |
| MD081 | No excessive emphasis | Excessive bold/italic emphasis in prose |
Code Block Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD014 | Commands show output | Code blocks should show output when appropriate |
| MD040 | Fenced code language | Fenced code blocks should have a language specified |
| MD046 | Code block style | Code block style |
| MD048 | Code fence style | Code fence style |
| MD078 | Missing chunk labels | Executable Quarto chunks should have a label |
| MD079 | Chunk label spaces | Quarto chunk labels must not contain whitespace |
Link and Image Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD011 | Reversed link | Reversed link syntax |
| MD034 | No bare URLs | Bare URL used |
| MD042 | No empty links | No empty links |
| MD045 | No alt text | Images should have alternate text |
| MD051 | Link fragments | Link fragments should be valid heading IDs |
| MD052 | Reference links images | References should be defined |
| MD053 | Link image definitions | Link and image reference definitions should be needed |
| MD054 | Link image style | Link and image style |
| MD059 | Link text | Link text should be descriptive |
Table Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD055 | Table pipe style | Table pipe style should be consistent |
| MD056 | Table column count | Table column count should be consistent |
| MD058 | Table spacing | Tables should be surrounded by blank lines |
| MD075 | Orphaned table rows | Orphaned table rows or headerless pipe content |
Footnote Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD066 | Footnote validation | Footnote references should have definitions and vice versa |
| MD067 | Footnote definition order | Footnote definitions should appear in order of reference |
| MD068 | Empty footnote definitions | Footnote definitions should not be empty |
Frontmatter Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD071 | Blank line after frontmatter | Frontmatter should be followed by a blank line |
| MD072 | Frontmatter key sort | Frontmatter keys should be sorted (YAML/TOML/JSON) |
Other Rules
| Rule ID | Rule Name | Description |
|---|---|---|
| MD057 | Relative links | Relative links should exist |
| MD060 | Table format | Table formatting should be consistent |
| MD061 | Forbidden terms | Certain terms should not be used |
| MD062 | Link destination space | No whitespace in link destinations |
| MD073 | TOC validation | Table of Contents should match headings |
| MD074 | MkDocs nav validation | Nav entries should point to existing files |
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.