Lists

How to use lists.

# Unordered marker

Use dashes - marker.

remark-lint: unordered-list-marker-style (opens new window)

👍 Correct code for this rule:

- One
- Two
- Three

👎 Incorrect code for this rule:

* One
* Two
* Three

+ One
+ Two
+ Three

# 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 avoid 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 (opens new window) and remark-lint-ordered-list-marker-value (opens new window)

👍 Correct code for this rule:

1. One
2. Two
  2.1 Two dot one
3. Three

👎 Incorrect code for this rule:

1. One
1. Two
  1.1 Two dot one
1. Three

1) One
1) Two
  1.1) Two dot one
1) Three

1) One
2) Two
  2.1) Two dot one
3) Three

# No content before

Make sure that there are no other characters (including spaces) in front of each list item.

remark-lint: list-item-bullet-indent (opens new window)

👍 Correct code for this rule:

- One
- Two
  - Two dot one
- Three

1. One
2. Two
  2.1 Two dot one
3. Three

👎 Incorrect code for this rule:

Note

The · character represents a space character.

x- One
 - Two
  .- Two dot one
"- Three
·- Four

x1. One
 2. Two
  .2.1 Two dot one
"3. Three
·4. Four

# Continuous indentation

Use two (2) spaces for continuous indentation of nested items and their content.

remark-lint: list-item-content-indent (opens new window) and list-item-indent (opens new window)

👍 Correct code for this rule:

- One
  - One dot one
- Two
  - Two dot one
- Three
  - Three dot one

👎 Incorrect code for this rule:

- One
    - One dot one
- Two
 - Two dot one
- Three
   - Three dot one

- One
    One dot one!
- Two
 Two dot one!
- Three
   Three dot one!

# Empty lines

A list must not contain blank lines between each list item.

remark-lint: list-item-spacing (opens new window)

👍 Correct code for this rule:

- One
- Two
  - Two dot one
- Three

👎 Incorrect code for this rule:

- One

- Two

  - Two dot one

- Three

# 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:

... a line with text.

- One
- Two
  - Two dot one
- Three

Another line with text...

👎 Incorrect code for this rule:

... a line wit text.
- One
- Two
  - Two dot one
- Three
Another line with text...

... a line with text.


- One
- Two
  - Two dot one
- Three


Another line with text...

# 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:

This is awesome

- The summer is hot.
- A lot of beautiful human beings.

Proper names or code snippets:

A list for

- React
- `String`

👎 Incorrect code for this rule:

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:

- One
- Two
- Three

The Winter is

- Sparkling and frozen.
- Cold and snowy.
- Bright and enlightened.

👎 Incorrect code for this rule:

- One.
- Two.
- Three.

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 (opens new window)

👍 Correct code for this rule:

- [x] One
- [ ] Two
- [x] Three

👎 Incorrect code for this rule:

- [!] One
- [~] Two
- [»] Three

* [] One
* [  ] Two
* [     ] Three

← Links Naming conventions →