MD082 - Headings should have content before the next heading¶

Aliases: no-empty-sections

Disabled by default. This rule is opt-in: enable it explicitly with extend-enable. There is no markdownlint equivalent; this is a rumdl-specific structure rule.

What this rule does¶

Flags any heading that is immediately followed by another heading with no rendered content in between. That gap is an empty section: a heading whose body is missing, either a parent heading with nothing under it before its first child, or sibling headings with no content between them.

The following does not count as a section body, so a section containing only these is still empty:

• blank lines
• HTML comments (<!-- ... -->)
• reference-link definitions ([ref]: url)
• lone thematic breaks (---, ***, ___)

Everything else that renders counts as content: paragraphs, lists, code blocks, tables, blockquotes, and raw HTML such as <div>.

A {#id} attribute list on the line immediately after a heading is its anchor and is treated as part of the heading, not as the section body. An attribute list elsewhere (for example, separated from the heading by a blank line) renders as ordinary text and counts as content.

Only a heading immediately followed by another heading is flagged. A trailing heading at the end of the document with no body is not flagged.

Why this matters¶

A sub heading directly under a parent heading with nothing in between usually means the document needs restructuring. A heading with no content can often be refactored away, and an empty section between two headings is rarely intentional in finished documentation.

Configuration¶

[MD082]
# Check every heading (1) or exempt H1 and check H2+ (2).
level = 1

Examples¶

Correct¶

# Project

A short introduction to the project.

## Installation

Run the installer.

Incorrect¶

# Project

## Installation

Run the installer.

# Project runs straight into ## Installation with no content in between, so the # Project section is empty.

Automatic fixes¶

None. Fixing would mean inventing a section body, which the rule cannot do safely, so it is diagnostic only.

Related rules¶

• MD022 - Headings should be surrounded by blank lines
• MD043 - Required heading structure