Indentation Character
Always use spaces characters where two (2) spaces are used for indentation. The usage of tab characters is disallowed. A tab could be a different number of columns depending on the environment, but a space is always one column. Adhering to this rule increases the code readability and maintainability significantly.
remark-lint: no-tabs
Examples
Note: The » character represents a tab.
⇣ Incorrect code for this rule:
The winter has sparkling and frozen elements!
» This line contains a tab character.
}
The winter has sparkling and frozen elements!
This line contains 4 space characters.
}
The winter has sparkling and frozen elements!
This line contains only 1 space character.
}
⇡ Correct code for this rule:
The winter has sparkling and frozen elements!
This line contains 2 space characters.
}
Newline
End files with a single newline character. Always use unix-style LF linebreaks (\n, denoted as ␊) and avoid the usage of Microsoft Windows CRLF characters (\r\n, denoted as ␍␊).
remark-lint: final-newline and linebreak-style
Examples
Note: The ¬ character represents a line break.
⇣ Incorrect code for this rule:
The winter has sparkling and frozen elements!
Many snowflakes are falling down.
The winter has sparkling and frozen elements!
Many snowflakes are falling down.¬
¬
⇡ Correct code for this rule:
The winter has sparkling and frozen elements!
Many snowflakes are falling down.¬
References
Before Blocks
Always add one (1) blank line before blocks except the first line of the file.
remark-lint: no-consecutive-blank-lines and no-missing-blank-lines
Examples
Note: The ¬ character represents a line break.
⇣ Incorrect code for this rule:
The winter has sparkling and frozen elements!
Many snowflakes are falling down.
⇡ Correct code for this rule:
The winter has sparkling and frozen elements!
¬
Many snowflakes are falling down.
After Sentences
Use a single space after sentences.
Examples
⇣ Incorrect code for this rule:
Many snowflakes are falling down. The winter has sparkling and frozen elements!
Many snowflakes are falling down.The winter has sparkling and frozen elements!
⇡ Correct code for this rule:
Many snowflakes are falling down. The winter has sparkling and frozen elements!
Maximum Line Length
In contrast to source code, where lines contain statements that can be almost always be broken up or indented, this rule can not be applied to flowing text. The author should be able to write sentences and text blocks without worrying about the line length.
Other style guides suggest to use line breaks after the character limit has been reached, but this will lead to deformed rendered output since GFM supports soft line breaks. Therefore, this guide advices to avoid using a character limit per line for flowing text, but try to use a maximum line length of 120 characters (including whitespaces) for all other document elements.
Instead of enforcing a maximum line length, users should use soft line wrapping:
- Soft wrapping allows line lengths to visually adjust automatically with adjustments to the width of the user's window or margin settings - This is a standard feature of all modern text editors like Atom or VSCode, IDEs like JetBrains IntelliJ IDEA, word processors, and email clients like Thunderbird.
- Using hard wrap inserts actual line breaks in the text at wrap points causing the Markdown to not look like the rendered output - With soft wrapping the actual text is still on the same line but will be rendered by the application like it's divided into several lines. This increases the readability significantly and leads to the same visual result as if a maximum line length with hard line breaks for flowing text would have been used.
- Less writer effort - The author can focus on the content instead of formatting.
Note that the rule for long strings is related to this rule, and should not be broken up.
remark-lint: maximum-line-length
Examples
⇣ Incorrect code for this rule:
> The winter and all of its fascinating, sparkling and
frozen elements and lively, diverse and beautiful wildlife.
Many snowflakes are falling down. The winter has sparkling and frozen elements! It is home
for many beautiful animals like snowy owls,
arctic foxes, and grizzly bears.
```js
const season = winter && winter.elements && winter.elements.snow && winter.elements.snow.state && winter.elements.snow.state.temperature && winter.elements.snow.state.temperature.celsius;
```
⇡ Correct code for this rule:
> The winter and all of its fascinating, sparkling and frozen elements and lively, diverse and beautiful wildlife.
Many snowflakes are falling down. The winter has sparkling and frozen elements! It is home for many beautiful animals like snowy owls, arctic foxes, and grizzly bears.
```js
const season = winter
&& winter.elements
&& winter.elements.snow
&& winter.elements.snow.state
&& winter.elements.snow.state.temperature
&& winter.elements.snow.state.temperature.celsius;
```
Trailing
Don't use trailing whitespace to generate a line break, use flowing text style or a blank line to create a new paragraph.
remark-lint: hard-break-spaces
Examples
Note: The · character represents a whitespace and the ¬ character represents a line break.
⇣ Incorrect code for this rule:
The winter has sparkling and frozen elements!··¬
Many snowflakes are falling down.
The winter has sparkling and frozen elements!¬
Many snowflakes are falling down.
⇡ Correct code for this rule:
The winter has sparkling and frozen elements! Many snowflakes are falling down.
The winter has sparkling and frozen elements!¬
Many snowflakes are falling down.