Md063 - Heading Capitalization¶

Aliases: heading-capitalization

What This Rule Does¶

Enforces consistent capitalization styles for markdown headings. This rule supports title case, sentence case, and all caps styles.

Note: This rule is disabled by default. You must explicitly enable it in your configuration.

Why This Matters¶

• Consistency: Ensures all headings follow the same capitalization style
• Professional appearance: Properly capitalized headings look more polished
• Readability: Consistent formatting helps readers navigate your document
• Style guide compliance: Many style guides require specific heading capitalization

Examples¶

Title Case (default)¶

Incorrect¶

# the quick brown fox
## getting started with javascript
### self-documenting code practices

Correct¶

# The Quick Brown Fox
## Getting Started with JavaScript
### Self-Documenting Code Practices

Sentence Case¶

Incorrect¶

# The Quick Brown Fox
## Getting Started With JavaScript

Correct¶

# The quick brown fox
## Getting started with JavaScript

All Caps¶

Incorrect¶

# introduction
## Getting Started

Correct¶

# INTRODUCTION
## GETTING STARTED

Configuration¶

Default Lowercase Words¶

a, an, and, as, at, but, by, for, in, nor, of, on, or, so, the, to, up, yet

Example Configurations¶

Enable With Title Case (default)¶

[MD063]
enabled = true
style = "title_case"

Sentence Case¶

[MD063]
style = "sentence_case"

All Caps¶

[MD063]
style = "all_caps"

Preserve Brand Names¶

[MD063]
style = "title_case"
ignore-words = ["iPhone", "macOS", "GitHub", "JavaScript", "TypeScript"]
preserve-cased-words = true

Only Check H1 and H2 Headings¶

[MD063]
style = "title_case"
min-level = 1
max-level = 2

Custom Lowercase Words¶

[MD063]
style = "title_case"
lowercase-words = ["a", "an", "the", "and", "but", "or", "for", "nor", "on", "at", "to", "by", "from", "with", "without", "into", "onto", "upon", "vs", "via"]

Special Handling¶

Inline Code¶

Inline code spans are preserved as-is:

# Using `const` in JavaScript

Becomes:

# Using `const` in JavaScript

The backticked content is never modified.

Links¶

Link text is capitalized, but URLs are preserved:

# See the [getting started](./guide.md) guide

Becomes:

# See the [Getting Started](./guide.md) Guide

Custom Header IDs¶

Custom header IDs (Kramdown syntax) are preserved:

# getting started {#intro}

Becomes:

# Getting Started {#intro}

Mixed-Case Words¶

When preserve-cased-words is enabled (default), words with internal capitals are preserved:

# using GitHub actions

Becomes:

# Using GitHub Actions

Note: "GitHub" is preserved because it has an internal capital letter.

Hyphenated Words¶

Each part of a hyphenated word is capitalized in title case:

# self-documenting code

Becomes:

# Self-Documenting Code

Automatic Fixes¶

This rule can automatically fix capitalization issues. Run:

rumdl fix yourfile.md

Related Rules¶

• MD025 - Single H1 heading
• MD026 - No trailing punctuation in heading
• MD044 - Proper names

Rationale¶

Consistent heading capitalization improves document readability and professionalism. This rule uses the titlecase crate which implements John Gruber's title case algorithm, ensuring proper handling of edge cases like articles, prepositions, and hyphenated words.

The rule is disabled by default because capitalization preferences vary widely between style guides (AP, Chicago, APA) and personal preferences. Enable it only if your project requires consistent heading capitalization.