Skip to content

heading-casing.md

Latest commit

 

History

History
362 lines (240 loc) · 10.4 KB

heading-casing.md

File metadata and controls

362 lines (240 loc) · 10.4 KB
pageClass rule-details
sidebarDepth 0
title markdown-preferences/heading-casing
description enforce consistent casing in headings.
since v0.9.0

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

{
  "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:

{
  "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:

{
  "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:

{
  "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

👫 Related Rules

🚀 Version

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

🔍 Implementation