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"

Sentence Case That Restarts After a Colon¶

[MD063]
style = "sentence-case"
sentence-case-restart-after = [":"]

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¶

Sentence Boundaries Inside a Heading¶

By default sentence case capitalizes only the heading's first word, so everything after a colon is lowercased:

# Requirement 1: Struct to Logger Slice Conversion

Becomes:

# Requirement 1: struct to logger slice conversion

Set sentence-case-restart-after to the punctuation that should start a new sentence:

[MD063]
style = "sentence-case"
sentence-case-restart-after = [":"]

Now the word after the colon is capitalized like the heading's first word:

# Requirement 1: Struct to logger slice conversion

Each entry is matched against the end of a word, so the boundary is only recognized where whitespace follows it. That is what keeps Well-Known Ports intact when - is configured, and leaves https://example.com/A/B alone when : is:

# Ports: Well-Known ports explained

A boundary with nothing after it (# Setup:) changes nothing, and words preserved by ignore-words, preserve-cased-words or an MD044 proper name keep winning over the restart, so iPhone after a colon stays iPhone rather than becoming IPhone.

Boundaries are recognized in the parts of a heading the rule capitalizes, which is plain text and link text:

# Topic [see:](./guide.md) More detail

Inline code, HTML and image alt text are preserved verbatim rather than capitalized, so a boundary inside one of them is not treated as a sentence break:

# Topic `see:` more detail

The default is empty, which is the behavior described at the top of this section.

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 check --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.