rumdl

The MD085 rule targets leading whitespace in top-level paragraphs to ensure that paragraphs look identical in the source regardless of how they were wrapped or edited.

What it changes

It removes leading spaces and tabs from continuation lines.

Incorrect:

This is some paragraph
 with line breaks
  and indentation.

Correct:

This is some paragraph
with line breaks
and indentation.

What it leaves alone (Structural Indentation)

To avoid breaking Markdown structure, the rule does not touch indentation in the following contexts:

• List item content (including lazy continuation lines)
• Blockquotes and their lazy continuation lines
• Tables, footnote bodies, and definition lists
• Code blocks (fenced or indented), HTML, math, and front matter blocks
• Flavor-specific containers (e.g., MkDocs admonitions, Pandoc/Quarto divs, MyST directives)
• Multi-line code spans
• HTML blocks (everything under a line beginning with < until the next blank line)
• Lines that would become a new block if the indentation were removed (e.g., lines starting with #, >, -, +, *, _, =, `, ~, <, |, [, {, :, $, !, % or a digit)

Important Nuances

• Prose vs. Blocks: A continuation line indented by four or more spaces is treated as prose and will be rewritten, because an indented code block cannot interrupt a paragraph.
• Hard Line Breaks: The rule only removes leading whitespace; it does not affect hard line breaks (like a backslash or two spaces at the end of a line).

The MyST flavor adjusts how rumdl interprets several structural patterns to prevent linting errors on valid MyST syntax:

Colon Directives

MyST uses ::: (or more colons) for structural containers. Nesting is supported by increasing the colon count.

• Opener: :::{name}
• Closer: ::: (matching the number of colons used in the opener)
• Linting: The body of colon directives is treated as normal Markdown prose and is linted accordingly.

Backtick Directives

MyST uses backtick code fences with a {name} info string (e.g., ```{note}).

• Content-bearing directives: For directives like note, warning, tip, figure, etc., the body is linted as Markdown.
• Code-bearing directives: For directives like code-cell, code-block, raw, eval-rst, and literalinclude, the body is treated as code and is not linted.

Roles (Inline Directives)

MyST roles use the pattern {rolename} followed by backtick-delimited content (e.g., {ref}label or `{math}`expression). These are recognized as valid syntax and are not flagged as malformed inline code.

Directive Options

Options can be specified as :key: value lines immediately after the opener. These lines are part of the directive and are not linted as prose.

:::{note}
This is a note admonition with **Markdown** content.
:::

::::{warning}
Outer directive.

:::{tip}
Inner directive.
:::
::::

```{figure} image.png
:alt: An image description
:width: 80%

Caption text with **Markdown** formatting.

See {ref}my-label for details.

The MD026 rule (alias: no-trailing-punctuation) removes trailing punctuation from the end of headings to maintain a clean, professional appearance and improve readability in tables of contents.

Automatic Fixes

When applied, rumdl will automatically:

• Remove periods, commas, semicolons, colons, and exclamation marks from heading endings.
• Preserve question marks (e.g., ## What is Markdown? remains unchanged).

Examples

Correct usage:

# Introduction

## What is Markdown?

### FAQ: Frequently Asked Questions

Incorrect usage (will be fixed):

# This is a sentence.

## Random heading;

### This seems wrong,

#### Important!

##### Ending with colon:

Fixed output:

# This is a sentence

## Random heading

### This seems wrong

#### Important

##### Ending with colon

# Introduction

## What is Markdown?

### FAQ: Frequently Asked Questions

#### Step 1: Getting Started

##### Chapter 2: Configuration

Because rumdl prioritizes CommonMark compliance and performance, some rules behave differently than markdownlint.

Key Rule Divergences

• MD004 (unordered-list-style): In consistent mode, rumdl uses prevalence-based detection (the most common marker wins; ties prefer dashes). markdownlint uses the first marker as the standard.
• MD005/MD007 (list-indent / ul-indent): rumdl uses parent-based dynamic indentation to handle ordered lists with variable marker widths (e.g., 1. vs 10.).
• MD012 (no-multiple-blanks): rumdl uses a filtered_lines() architecture to skip frontmatter and code blocks, which may result in different counts near block boundaries.
• MD013 (line-length): rumdl exempts unbreakable lines (URLs, long code spans) and supports a line_length = 0 setting for unlimited length. It also includes a math-blocks option (default true) to exempt display-math ($$ ... $$) from length checks.
• MD027 (no-multiple-space-blockquote): rumdl's list-items option defaults to false to reduce noise in blockquotes. Set list-items = true for strict markdownlint parity.
• MD029 (ordered-list-prefix): rumdl uses CommonMark AST start values. It only auto-fixes when start_value == 1 to preserve explicit numbering intent.
• MD051 (link-fragments): rumdl's ignore-case option defaults to true. Set ignore-case = false for strict markdownlint parity.

The MD087 rule identifies 'dead' disable comments—comments that are present but no longer serve a purpose because the violation they were meant to suppress no longer exists.

Why use it?

Disable comments often persist after code is refactored. If a long URL is shortened, a rumdl-disable-line MD013 comment might remain. This silently keeps coverage turned off for a rule that is no longer needed. MD087 flags these to ensure your linting coverage remains accurate.

Examples

Incorrect (triggers MD087):

A short line. <!-- rumdl-disable-line MD013 -->

In this case, MD013 has nothing to report on this line, so the comment is useless.

Correct:

<!-- rumdl-disable-next-line MD013 -->
A line so long that it genuinely exceeds the configured limit, which is what the comment is for.

Partial Suppression: If a comment names multiple rules, MD087 will report only the specific rules that suppressed nothing:

Text with <b>html</b>. <!-- rumdl-disable-line MD033 MD013 -->

If MD033 fires but MD013 does not, the error message will name MD013 alone.

What MD087 ignores

• Rules that are not part of the current run (e.g., disabled in config, excluded via --disable, or in per-file-ignores).
• Comments with no rule name (e.g., <!-- rumdl-disable -->).
• Comments inside fenced or indented code blocks.
• <!-- prettier-ignore --> comments.
• Unknown rule names (e.g., MD999).