Skip to content

MD026 - Keep headings clean and professional

Aliases: no-trailing-punctuation

What this rule does

Removes trailing punctuation from the end of headings to maintain a clean, professional appearance. Question marks are allowed by default for FAQ-style headings.

Why this matters

  • Professional appearance: Clean headings look more polished and professional
  • Better readability: Unnecessary punctuation can distract readers
  • Consistent style: Maintains a uniform look throughout your document
  • Navigation clarity: Clean headings work better in tables of contents and outlines

Examples

✅ Correct

# Introduction

## What is Markdown?

### FAQ: Frequently Asked Questions

#### Step 1: Getting Started

##### Chapter 2: Configuration

❌ Incorrect

# This is a sentence.

## Random heading;

### This seems wrong,

#### Important!

##### Ending with colon:

🔧 Fixed

# This is a sentence

## Random heading

### This seems wrong

#### Important

##### Ending with colon

Configuration

[MD026]
punctuation = ".,;:!"  # Characters to remove from heading endings (default: ".,;:!")

To allow exclamation marks in headings, remove ! from the list:

[MD026]
punctuation = ".,;:"

Automatic fixes

This rule will:

  • Remove periods, commas, semicolons, colons, and exclamation marks from heading endings (default: .,;:!)
  • Preserve question marks for FAQ-style headings ("What is Markdown?")
  • You can customize the punctuation list if you want to allow certain characters

Markdown with Gherkin

Under the mdg flavor, the ASCII colon leaves the punctuation set, whether it arrived from the default or from an explicit configuration. A Gherkin structure is an ATX heading spelled Keyword: name, so the colon after the keyword is what makes the keyword a keyword, and this rule must never be able to delete it.

Because MD026 matches punctuation only at the very end of a heading, dropping the colon from the set is complete: no heading whose last character is a colon is inspected at all, so ## Scenario!: is left exactly as written. Only the ASCII colon leaves the set — a full-width ： carries no structural meaning, so a punctuation value that lists one keeps enforcing it.

When MD026 reaches relevant content with an explicit punctuation value containing a colon, it prints one [config warning] line on stderr; the colon is dropped either way.

See Markdown with Gherkin Flavor for the full flavor specification.

Learn more