Lists
Key Point
💡 How to uses lists.
Unordered marker
Use dashes - marker.
remark-lint: unordered-list-marker-style
👍 Correct code for this rule:
- Winter
- Snow
- Frost
👎 Incorrect code for this rule:
* Winter
* Snow
* Frost
+ Winter
+ Snow
+ Frost
Ordered marker
Use continuous numerating marker for ordered list items.
This increases the readability and overview and allows to refer to items by their number in the same markdown file or externally.
It also allows to create sub-items which is impossible if the same number will be used for all top-level items.
The marker character must be a dot (.), characters like a closing brace ()) are not allowed since they are only supported in CommonMark.
The only disadvantage is that references break when a new list item is added.
This problem can be reduced by
- Using an unordered list until the final structure and layout has been determined.
- Keeping references close to the list to avoind forgetting to update them.
- Always specify an specific version of the markdown file when referring from an external document.
remark-lint: ordered-list-marker-style and remark-lint-ordered-list-marker-value
👍 Correct code for this rule:
1. Winter
2. Snow
2.1 Snowflakes
3. Frost
👎 Incorrect code for this rule:
1. Winter
1. Snow
1.1 Snowflakes
1. Frost
1) Winter
1) Snow
1.1) Snowflakes
1) Frost
1) Winter
2) Snow
2.1) Snowflakes
3) Frost
No content before
Make sure that there are no other characters (including whitespaces) in front of each list item.
remark-lint: list-item-bullet-indent
👍 Correct code for this rule:
- Winter
- Snow
- Snowflakes
- Frost
1. Winter
2. Snow
2.1 Snowflakes
3. Frost
👎 Incorrect code for this rule:
Note
The · character represents a whitespace character.
x- Winter
- Snow
.- Snowflakes
"- Frost
·- Frost
x1. Winter
2. Snow
.2.1 Snowflakes
"3. Frost
·3. Frost
Continuous indentation
Use two (2) whitespaces for continuous indentation of nested items and their content.
remark-lint: list-item-content-indent and list-item-indent
👍 Correct code for this rule:
- Winter
- Snow
- Snowflakes
- Frost
- Arctic
- Sparkling
- Frozen
- Winter
Sparkling and frozen!
- Snowflakes
Made of snow!
- Snow
Falls down!
Arctic beauty
- Winter
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```
Snow
```java
import winter.Snow;
String[] flakes = Snow.getFlakes();
```
- Frost
> Sparkling and frozen!
👎 Incorrect code for this rule:
- Winter
- Snow
- Snowflakes
- Frost
- Arctic
- Sparkling
- Frozen
- Winter
Sparkling and frozen!
- Snowflakes
Made of snow!
- Snow
Falls down!
Arctic beauty
- Winter
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```
- Snow
```java
import static winter.Snow;
String[] flakes = Snow.getFlakes();
```
- Frost
> Sparkling and frozen!
Empty lines
A list must not contain blank lines between each list item.
remark-lint: list-item-spacing
👍 Correct code for this rule:
- Winter
- Snow
- Snowflakes
- Frost
👎 Incorrect code for this rule:
- Winter
- Snow
- Snowflakes
- Frost
Empty lines before and after
Always surround lists by a single empty line except at the beginning of the file.
👍 Correct code for this rule:
... snowflakes are falling.
- Winter
- Snow
- Snowflakes
- Frost
Sparkling and frozen...
👎 Incorrect code for this rule:
... snowflakes are falling.
- Winter
- Snow
- Snowflakes
- Frost
Sparkling and frozen...
... snowflakes are falling.
- Winter
- Snow
- Snowflakes
- Frost
Sparkling and frozen...
Letter case
Use upper cases for enumerations because most of the time the content is a noun, proper name, code snippet or standalone sentence.
When the list items are meant to be imaginary concatenated with the sentence that comes before the list, adapt to the same case as the context.
👍 Correct code for this rule:
The winter has
- Many snowflakes that are falling down.
- Sparkling and frozen elements!
- A lot of beautiful animals like snowy owls, arctic foxes, and grizzly bears.
Enumerations or context-dependent:
The winter has
- **Snowflakes** - They are falling down.
- **Elements** - They are sparkling and frozen!
- **Beautiful animals** - e.g a lot of snowy owls, arctic foxes, and grizzly bears.
Proper names or code snippets:
A list for
- React
- `String`
👎 Incorrect code for this rule:
The winter has
- many snowflakes that are falling down.
- sparkling and frozen elements!
- a lot of beautiful animals like snowy owls, arctic foxes, and grizzly bears.
Enumerations or context-dependent:
The winter has
- **snowflakes** - They are falling down.
- **elements** - They are sparkling and frozen!
- **beautiful animals** - Like e.g a lot of snowy owls, arctic foxes, and grizzly bears.
Proper names or code snippets:
A list for
- react
- `string`
Punctuation after items
Use punctuation at the end of a list item when it contains a sentence that starts with an upper case letter or multiple sentences or paragraphs.
Omit the punctuation for single words.
👍 Correct code for this rule:
- Winter
- Snow
- Frost
The Winter is
- Sparkling and frozen.
- Cold and snowy.
- Bright and enlightened.
👎 Incorrect code for this rule:
- Winter.
- Snow.
- Frost.
The Winter is
- sparkling and frozen
- cold and snowy
- bright and enlightened
Checkbox character style
Use x for ticked checkboxes and a single space for non ticked checkboxes.
remark-lint: checkbox-character-style
👍 Correct code for this rule:
- [x] Winter
- [ ] Snow
- [x] Frost
👎 Incorrect code for this rule:
- [!] Winter
- [~] Snow
- [»] Frost
* [] Winter
* [ ] Snow
* [ ] Frost