MD021 - Multiple Spaces Inside Hashes on Closed ATX Style Heading

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule ensures closed ATX-style headings have only a single space inside the hash markers. Multiple spaces create inconsistent formatting and unnecessary whitespace.

Why This Rule Exists

Single space inside closed headings is important because:

Maintains consistent formatting
Follows standard markdown conventions
Improves readability
Ensures proper rendering across different parsers

Examples

❌ Incorrect (violates rule)

#  Heading with multiple spaces  #
##   Another heading   ##
###    Too many internal spaces    ###

✅ Correct

# Heading with single spaces #
## Another heading ##
### Properly spaced heading ###
# Open heading is also fine

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

Reduce multiple spaces to single spaces inside hash markers
Preserve the heading level and content
Maintain the closed heading style

Apply Fix

# Fix multiple spaces in closed headings
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

Your style guide requires multiple spaces for alignment
You prefer open ATX headings (without closing hashes)

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD021"]

Disable Inline

<!-- mdbook-lint-disable MD021 -->
##   Heading with multiple spaces   ##
<!-- mdbook-lint-enable MD021 -->

MD018 - No space after hash on ATX heading
MD019 - Multiple spaces after hash on ATX heading
MD020 - No space inside hashes on closed ATX heading
MD022 - Headings should be surrounded by blank lines
MD003 - Heading style

mdbook-lint Documentation