Heading Rules

A heading for the purpose of the Linter is an ATX header. It does not currently support Setext headers (see this issue).

Capitalize headings

Alias: capitalize-headings

Headings should be formatted with capitalization

Options

Name	Description	List Items	Default Value
`Style`	The style of capitalization to use	`Title Case`: Capitalize Using Title Case Rules `ALL CAPS`: CAPITALIZE THE WHOLE TITLE `First letter`: Only capitalize the first letter	`Title Case`
`Ignore cased words`	Only apply title case style to words that are all lowercase	N/A	`true`
`Ignore words`	A list of words to ignore when capitalizing	N/A	`null`
`Lowercase words`	A list of words to keep lowercase	N/A	`null`
`Characters to ignore at the start of potential words`	Characters that by themselves may precede one or more letters, single quotes, and/or dashes and have it be considered a word	N/A	`'"(‘“-`
`Characters to ignore at the end of potential words`	Characters that may follow one or more letters, single quotes, and/or dashes and have it be considered a word	N/A	`.?!,:;'")”’0123456789-`

Examples

With `Title case=true`, `Ignore cased words=false`

Before:

# this is a heading 1
## THIS IS A HEADING 2
### a heading 3

After:

# This is a Heading 1
## This is a Heading 2
### A Heading 3

With `Title Case=true`, `Ignore cased words=true`

Before:

# this is a heading 1
## THIS IS A HEADING 2
### a hEaDiNg 3

After:

# This is a Heading 1
## THIS IS A HEADING 2
### A hEaDiNg 3

With `First letter=true`

Before:

# this is a heading 1
## this is a heading 2

After:

# This is a heading 1
## This is a heading 2

With `ALL CAPS=true`

Before:

# this is a heading 1
## this is a heading 2

After:

# THIS IS A HEADING 1
## THIS IS A HEADING 2

File name heading

Alias: file-name-heading

Inserts the file name as a H1 heading if no H1 heading exists.

Examples

Inserts an H1 heading

Before:

This is a line of text

After:

# File Name
This is a line of text

Inserts heading after YAML front matter

Before:

---
title: My Title
---
This is a line of text

After:

---
title: My Title
---
# File Name
This is a line of text

Header increment

Alias: header-increment

Heading levels should only increment by one level at a time

Options

Name	Description	List Items	Default Value
`Start header increment at heading level 2`	Makes heading level 2 the minimum heading level in a file for header increment and shifts all headings accordingly so they increment starting with a level 2 heading.	N/A	false

Examples

Heading levels are decremented as needed

Before:

# H1
### H3
### H3
#### H4
###### H6

We skipped a 2nd level heading

After:

# H1
## H3
## H3
### H4
#### H6

We skipped a 2nd level heading

Skipped headings in sections that would be decremented will result in those headings not having the same meaning

Before:

# H1
### H3

We skip from 1 to 3

###### H6

We skip from 3 to 6 leaving out 4, 5, and 6. Thus headings level 4 and 5 will be treated like H3 above until another H2 or H1 is encountered

##### H5

We skipped 5 previously so it will be treated the same as the H3 above since it was the next lowest header that was to be decremented

## H2

This resets the decrement section so the H6 below is decremented to an H3

###### H6

After:

# H1
## H3

We skip from 1 to 3

### H6

We skip from 3 to 6 leaving out 4, 5, and 6. Thus headings level 4 and 5 will be treated like H3 above until another H2 or H1 is encountered

## H5

We skipped 5 previously so it will be treated the same as the H3 above since it was the next lowest header that was to be decremented

# H2

This resets the decrement section so the H6 below is decremented to an H3

## H6

When `Start header increment at heading level 2 = true`, H1s become H2s and the other headers are incremented accordingly

Before:

# H1 becomes H2
#### H4 becomes H3
###### H6
## H2
###### H6
# H1
## H2

After:

## H1 becomes H2
### H4 becomes H3
#### H6
## H2
### H6
## H1
### H2

Headings start line

Alias: headings-start-line

Headings that do not start a line will have their preceding whitespace removed to make sure they get recognized as headers.

Examples

Removes spaces prior to a heading

Before:

   ## Other heading preceded by 2 spaces ##
_Note that if the spacing is enough for the header to be considered to be part of a codeblock it will not be affected by this rule._

After:

## Other heading preceded by 2 spaces ##
_Note that if the spacing is enough for the header to be considered to be part of a codeblock it will not be affected by this rule._

Tags are not affected by this

Before:

  #test
  # Heading &amp;

After:

  #test
# Heading &amp;

Remove trailing punctuation in heading

Alias: remove-trailing-punctuation-in-heading

Removes the specified punctuation from the end of headings making sure to ignore the semicolon at the end of HTML entity references.

Options

Name	Description	List Items	Default Value
`Trailing punctuation`	The trailing punctuation to remove from the headings in the file.	N/A	`.,;:!。，；：！`

Examples

Removes punctuation from the end of a heading

Before:

# Heading ends in a period.
## Other heading ends in an exclamation mark! ##

After:

# Heading ends in a period
## Other heading ends in an exclamation mark ##

HTML Entities at the end of a heading is ignored

Before:

# Heading 1
## Heading &amp;

After:

# Heading 1
## Heading &amp;

Removes punctuation from the end of a heading when followed by whitespace

Before:

# Heading 1!  
## Heading 2.

After:

# Heading 1  
## Heading 2