Headings
Always use short and understandable headings.
# ATX Style
Always use atx-style (opens new window) headings (not closed) instead of Setext (opens new window).
The level can be seen and the number of characters must not match in both lines.
ATX also works for all levels, while Setext only goes up to level 2.
remark-lint: heading-style (opens new window)
👍 Correct code for this rule:
# One
## Two
### Three
👎 Incorrect code for this rule:
One
===
Two
---
No closed ATX styled headings:
# One #
## Two ##
### Three ###
# Empty lines before and after
Always surround headers by a single empty line except at the beginning of the file.
👍 Correct code for this rule:
... some content.
# One
Sparkling and awesome...
👎 Incorrect code for this rule:
... some content.
# One
Sparkling and awesome...
... some content.
# One
Sparkling and awesome...
# Content spacing
Always separate the marker character # from the actual header content using a single space.
remark-lint: no-heading-content-indent (opens new window)
👍 Correct code for this rule:
# One
👎 Incorrect code for this rule:
#One
# One
# No Content Before
Make sure that there are no other characters (including spaces) in front of headings.
remark-lint: no-heading-indent (opens new window)
👍 Correct code for this rule:
# One
Note
Note: The · character represents a space character.
👎 Incorrect code for this rule:
.# One
·# One
# No Duplicate
Avoid using two or more headers with the same content in the same markdown file. Many Markdown renderer generate IDs for headers based on the header content.
remark-lint: remark-lint-no-duplicate-headings (opens new window) and remark-lint-no-duplicate-headings-in-section (opens new window)
👍 Correct code for this rule:
# One
## One One
# Two
## Two Two
👎 Incorrect code for this rule:
# One
## Two
# Three
## One
# Sentences case
Use an upper case letter as the first letter of a header, unless it is a word that always starts with lowercase letters, for example proper names or code snippets.
👍 Correct code for this rule:
# The quick brown fox jumps over the lazy dog
Proper names or code snippets:
# React
# `string`
# init main
👎 Incorrect code for this rule:
# summer is hot
Proper names or code snippets:
# react
# `String`
# Init
# Length
Prefer using short header with a maximum length of 80 character (without markers).
Instead of using a long sentence, make the header a summary and write the long sentence as the first paragraph beneath the header.
This makes it effortless to refer to the header later, specially if automatic IDs or a TOC (Table Of Content) are created.
remark-lint: maximum-heading-length (opens new window)
👍 Correct code for this rule:
# One
The summer is sparkling and awesome!
👎 Incorrect code for this rule:
# The summer is sparkling and awesome!
# Punctuation after content
Do not use any punctuation at the end of a header
for example a trailing (semi)colon ;:, period ., closing marker # or any "sentence amplifier" (!?).
Every header is an introduction to what is about to come next, which is exactly the function of a colon.
Also the header is not a sentence, or at least only a short sentence, so there is not need to add a sentence separator to it.
remark-lint: no-heading-punctuation (opens new window)
👍 Correct code for this rule:
# One
Sparkling and awesome.
👎 Incorrect code for this rule:
# One: Sparkling
# One. Frozen.
# One #