markdown-preferences/heading-casing

enforce consistent casing in headings.

🔧 The --fix option on the command line can automatically fix some of the problems reported by this rule.

📖 Rule Details

This rule enforces consistent casing conventions for headings in Markdown files. Proper heading capitalization improves readability and maintains a professional appearance in documentation.

Examples

Default Configuration (`"Title Case"`)

The rule comes with extensive default values for preserveWords and ignorePatterns, making it work well out-of-the-box for technical documentation.

<!-- eslint markdown-preferences/heading-casing: 'error' -->

<!-- ✓ GOOD -->

# Introduction to Markdown Preferences

## Getting Started With the ESLint Plugin

### How to Configure Your JavaScript Rules

#### Working With APIs and JSON Files

##### Using TypeScript v2.1.3 Features

<!-- ✗ BAD -->

# introduction
 to markdown
 preferences


## getting
 started
 with
 the eslint
 plugin


### HOW
 TO
 CONFIGURE
 YOUR
 JAVASCRIPT
 RULES


# how
 To
 configure
 Your javascript
 Rules

With `"Sentence case"` Configuration

<!-- eslint markdown-preferences/heading-casing: ['error', { style: 'Sentence case' }] -->

<!-- ✓ GOOD -->

# Introduction to Markdown preferences

## Getting started with the plugin

### How to configure your ESLint rules

<!-- ✗ BAD -->

# Introduction To
 Markdown Preferences


## Getting Started
 With
 The
 Plugin


### HOW
 TO
 CONFIGURE
 YOUR
 ESLINT
 RULES

With `preserveWords` Option

<!-- eslint markdown-preferences/heading-casing: ['error', { style: 'Title Case', preserveWords: ['ESLint', 'JavaScript', 'TypeScript', 'GitHub'] }] -->

<!-- ✓ GOOD -->

# Getting Started With ESLint

## Working With JavaScript and TypeScript

### Using the GitHub API

<!-- ✗ BAD -->

# Getting Started With Eslint


## Working With Javascript
 and Typescript


### Using the Github
 API

Using `ignorePatterns` for Technical Terms

<!-- eslint markdown-preferences/heading-casing: ['error', { style: 'Title Case', ignorePatterns: ['/^v\\d+/u', '/\\w+\\.json$/u'] }] -->

<!-- ✓ GOOD -->

# Working With v2.0.1 and config.json Files

<!-- ✗ BAD -->

# working
 with
 v2.0.1 and config.json files

Customizing `minorWords` for Title Case

<!-- eslint markdown-preferences/heading-casing: ['error', { style: 'Title Case', minorWords: ['a', 'the', 'and', 'or', 'but', 'of', 'in', 'on', 'at', 'to', 'for', 'with'] }] -->

<!-- ✓ GOOD -->

# A Guide to Writing with Custom Minor Words

## The Best Practices for Writing

### Working with Custom Words and Settings

#### Tips for Writing on the Web

<!-- ✗ BAD -->

# A Guide To
 Writing With
 Custom Minor Words

## The Best Practices For
 Writing

### Working With
 Custom Words And
 Settings

#### Tips For
 Writing On
 The
 Web

When Not to Use

If your project uses specific branding or technical terms that require non-standard capitalization
If you're working with existing content that has deliberate capitalization choices
If your documentation uses a different style guide that conflicts with title case or sentence case

🔧 Options

json

{
  "markdown-preferences/heading-casing": [
    "error",
    {
      "style": "Title Case", // or "Sentence case"
      "preserveWords": ["ESLint", "JavaScript", "TypeScript"], // optional
      "ignorePatterns": ["/^v\\d+/u", "/\\w+\\.[a-z\\d]+$/u"], // optional
      "minorWords": ["a", "an", "the", "and", "or", "but"] // optional
    }
  ]
}

style (optional): The casing style to enforce for headings. Can be "Title Case" (default) or "Sentence case".
preserveWords (optional): An array of words that should be preserved with their exact casing, regardless of the chosen style. The matching is case-insensitive. Includes extensive defaults for common technical terms.
ignorePatterns (optional): An array of regular expression patterns for words that should be ignored during casing checks. Words matching any of these patterns will be left unchanged. Includes useful defaults for version numbers, file extensions, and technical patterns.
minorWords (optional): An array of words that should not be capitalized in Title Case (unless they're the first or last word). Includes defaults for articles, conjunctions, and prepositions.

`style` (`string`)

The casing style to enforce for headings.

Available Options:

"Title Case" (default): Enforces Title Case capitalization where major words are capitalized. Articles, conjunctions, and short prepositions remain lowercase unless they are the first or last word.
"Sentence case": Enforces Sentence case capitalization where only the first letter of the heading is capitalized, and the rest are lowercase.

`preserveWords` (`string[]`)

An array of words that should be preserved with their exact casing, regardless of the chosen style. The matching is case-insensitive.

Example:

json

{
  "preserveWords": ["ESLint", "JavaScript", "TypeScript", "HTML", "CSS", "JSON"]
}

Default Values:

The rule comes with an extensive list of common technical terms as default values.

Please see the defaultPreserveWords for the complete list.

You can also import and use the default preserve words in your JavaScript code:

import plugin from "eslint-plugin-markdown-preferences";

// Use in your ESLint configuration
export default {
  plugins: ["markdown-preferences"],
  rules: {
    "markdown-preferences/heading-casing": [
      "error",
      {
        style: "Title Case",
        preserveWords: [
          ...plugin.resources.defaultPreserveWords, // Include all default words
          "MyCustomBrand", // Add your custom words
          "MyAPI",
        ],
      },
    ],
  },
};

`ignorePatterns` (`string[]`)

An array of regular expression patterns for words that should be ignored during casing checks. Words matching any of these patterns will be left unchanged.

Example:

json

{
  "ignorePatterns": [
    "/^v\\d+/u", // Version numbers starting with 'v' (e.g., v1, v2.0.1)
    "/\\w+\\.[a-z\\d]+$/u", // File extensions and names (e.g., config.json, package.json, index.html)
    "/\\w*(?:API|Api)$/u", // Words ending with API (e.g., webAPI, restAPI)
    "/\\w*(?:SDK|Sdk)$/u", // Words ending with SDK (e.g., nodeSDK, javaSDK)
    "/\\w*(?:CLI|Cli)$/u" // Words ending with CLI (e.g., nodeCLI, gitCLI)
  ]
}

Default Values:

The rule includes several useful default patterns:

/^v\\d+/u - Version numbers starting with 'v' (e.g., v1.2.3, v2.0.1)
/\\w+\\.[a-z\\d]+$/u - File extensions and names (e.g., config.json, package.json, index.html)
/\\w*(?:API|Api)$/u - Words ending with API (e.g., webAPI, restAPI)
/\\w*(?:SDK|Sdk)$/u - Words ending with SDK (e.g., nodeSDK, javaSDK)
/\\w*(?:CLI|Cli)$/u - Words ending with CLI (e.g., nodeCLI, gitCLI)

This is particularly useful for:

Version numbers: v1.0.0, 2.5.1
Technical identifiers: API_KEY, config.json, camelCase
File names: package.json, tsconfig.json
Code patterns: snake_case, kebab-case
Numbers: test123, rule1, step2

Note: If a pattern is invalid (e.g., contains syntax errors), it will be silently ignored and won't affect the rule's operation.

`minorWords` (`string[]`)

An array of words that should not be capitalized in Title Case (unless they're the first or last word). This option allows you to customize which words are considered "minor" words in your documentation.

Example:

json

{
  "minorWords": [
    "a",
    "an",
    "the",
    "and",
    "or",
    "but",
    "of",
    "in",
    "on",
    "at",
    "to",
    "for",
    "with"
  ]
}

Default Values:

The rule comes with a comprehensive list of common English minor words:

Please see the defaultMinorWords for the complete list.

You can also import and use the default minor words in your JavaScript code:

import plugin from "eslint-plugin-markdown-preferences";

// Use in your ESLint configuration
export default {
  plugins: ["markdown-preferences"],
  rules: {
    "markdown-preferences/heading-casing": [
      "error",
      {
        style: "Title Case",
        minorWords: [
          ...plugin.resources.defaultMinorWords, // Include all default minor words
          "via", // Add your custom minor words
          "per",
        ],
      },
    ],
  },
};

Usage Example:

<!-- eslint markdown-preferences/heading-casing: ['error', { style: 'Title Case', minorWords: ['a', 'the', 'and', 'or', 'but', 'of', 'in', 'on', 'at', 'to', 'for', 'with'] }] -->

<!-- ✓ GOOD -->

# A Guide to Writing with Custom Minor Words

## The Best Practices for Writing

### Working with Custom Words and Settings

<!-- ✗ BAD -->

# A Guide To
 Writing With
 Custom Minor Words

## The Best Practices For
 Writing

### Working With
 Custom Words And
 Settings

This option is only effective when style is set to "Title Case". In "Sentence case", all words except the first one are lowercase regardless of this setting.

📚 Further Reading

markdown-preferences/hard-linebreak-style - enforce consistent hard linebreak style

🚀 Version

This rule was introduced in eslint-plugin-markdown-preferences v0.9.0

markdown-preferences/heading-casing ​

📖 Rule Details ​

Examples ​

Default Configuration ("Title Case") ​

With "Sentence case" Configuration ​

With preserveWords Option ​

Using ignorePatterns for Technical Terms ​

Customizing minorWords for Title Case ​

When Not to Use ​

🔧 Options ​

style (string) ​

preserveWords (string[]) ​

ignorePatterns (string[]) ​

minorWords (string[]) ​

📚 Further Reading ​

👫 Related Rules ​

🚀 Version ​

🔍 Implementation ​

markdown-preferences/heading-casing

📖 Rule Details

Examples

Default Configuration (`"Title Case"`)

With `"Sentence case"` Configuration

With `preserveWords` Option

Using `ignorePatterns` for Technical Terms

Customizing `minorWords` for Title Case

When Not to Use

🔧 Options

`style` (`string`)

`preserveWords` (`string[]`)

`ignorePatterns` (`string[]`)

`minorWords` (`string[]`)

📚 Further Reading

👫 Related Rules

🚀 Version

🔍 Implementation