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 comma separated list of words to ignore when capitalizing	N/A	`macOS, iOS, iPhone, iPad, JavaScript, TypeScript, AppleScript, I`
`Lowercase Words`	A comma separated list of words to keep lowercase	N/A	a, an, the, aboard, about, abt., above, abreast, absent, across, after, against, along, aloft, alongside, amid, amidst, mid, midst, among, amongst, anti, apropos, around, round, as, aslant, astride, at, atop, ontop, bar, barring, before, B4, behind, below, beneath, neath, beside, besides, between, 'tween, beyond, but, by, chez, circa, c., ca., come, concerning, contra, counting, cum, despite, spite, down, during, effective, ere, except, excepting, excluding, failing, following, for, from, in, including, inside, into, less, like, minus, modulo, mod, near, nearer, nearest, next, notwithstanding, of, o', off, offshore, on, onto, opposite, out, outside, over, o'er, pace, past, pending, per, plus, post, pre, pro, qua, re, regarding, respecting, sans, save, saving, short, since, sub, than, through, thru, throughout, thruout, till, times, to, t', touching, toward, towards, under, underneath, unlike, until, unto, up, upon, versus, vs., v., via, vice, vis-à-vis, wanting, with, w/, w., c̄, within, w/i, without, 'thout, w/o, abroad, adrift, aft, afterward, afterwards, ahead, apart, ashore, aside, away, back, backward, backwards, beforehand, downhill, downstage, downstairs, downstream, downward, downwards, downwind, east, eastward, eastwards, forth, forward, forwards, heavenward, heavenwards, hence, henceforth, here, hereby, herein, hereof, hereto, herewith, home, homeward, homewards, indoors, inward, inwards, leftward, leftwards, north, northeast, northward, northwards, northwest, now, onward, onwards, outdoors, outward, outwards, overboard, overhead, overland, overseas, rightward, rightwards, seaward, seawards, skywards, skyward, south, southeast, southwards, southward, southwest, then, thence, thenceforth, there, thereby, therein, thereof, thereto, therewith, together, underfoot, underground, uphill, upstage, upstairs, upstream, upward, upwards, upwind, west, westward, westwards, when, whence, where, whereby, wherein, whereto, wherewith, although, because, considering, given, granted, if, lest, once, provided, providing, seeing, so, supposing, though, unless, whenever, whereas, wherever, while, whilst, ago, inasmuch, even, whether, whose, whoever, why, how, whatever, what, both, and, or, either, neither, nor, just, rather, such, that, yet, is, it

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