Lists

Unordered Lists

Any of -, *, or + followed by a space starts a bullet. Pick one and keep it, because changing the marker starts a new list.

- first item
- second item
- third item

* also valid
+ also valid

- item one
- item two
* item three, this starts a SECOND list

- is the conventional choice, and the one prettier and markdownlint default to. * collides visually with emphasis, and + is rare enough that some editors do not highlight it.

Ordered Lists

A number, then . or ), then a space.

1. first
2. second
3. third

The numbers after the first are ignored. Every one of these renders as 1, 2, 3.

1. first
1. second
1. third

1. first
7. second
3. third

Writing 1. on every line is a real technique, not laziness: inserting a step in the middle never requires renumbering, and the diff stays one line. The counter starts from the first number, so a list can begin anywhere.

5. this renders as item 5
6. and this as 6
7. and this as 7

Only the starting number matters. 0. starts at zero in GFM. To use ) instead of ., be aware that CommonMark supports it and several older parsers do not.

1) parenthesis form, CommonMark
2) works on GitHub

Nesting and the Indentation Trap

Indent a child item to nest it. How much indentation is required is the single most common Markdown bug.

The CommonMark rule: a child must be indented to at least the column where the parent's content begins. For - that is 2 spaces, for 1. it is 3 spaces, for 10. it is 4.

- parent
  - child, 2 spaces, correct under a dash
    - grandchild, 4 spaces

1. parent
   1. child, 3 spaces, correct under "1. "
      1. grandchild, 6 spaces

Two spaces under an ordered item is not enough in CommonMark, but the original Markdown.pl and some legacy renderers accepted it, which is why old files nest inconsistently. Four spaces is the portable answer: it satisfies every parser for both list types.

1. parent
  - this may render as a sibling, not a child
1. parent
    - four spaces always nests correctly

Mixing types is fine, and often clearer:

1. Install the tool
   - macOS: use the package manager
   - Linux: download the tarball
2. Run it

Loose and Tight Lists

A tight list has no blank lines between items and renders each item's text bare. A loose list has at least one blank line between items, and every item gets wrapped in a <p>, which adds vertical spacing.

- tight
- tight
- tight

- loose

- loose

- loose

One blank line anywhere in the list makes the whole list loose, not just that item. That is why a list sometimes suddenly gains spacing after you add a paragraph to one item.

- this list is now loose
- because the next item has two paragraphs

- second item, first paragraph

  second item, second paragraph

Multi-Block Items

A list item can contain paragraphs, code fences, quotes, and nested lists. Indent the continuation to the item's content column.

1. Install the dependencies:

   ```bash
   npm install
   ```

   Then verify the version.

2. Start the server:

   ```bash
   npm run dev
   ```

Lazy continuation means a plain wrapped paragraph line does not strictly need the indentation, because the parser attaches it to the open item anyway.

- this item's text wraps onto
the next line without indentation and still
belongs to the item

That works, but a following block element (a fence, a nested list, a quote) does need proper indentation, so indenting consistently avoids a class of bug that only appears when you add a code block later.

Task Lists

Task lists are a GFM extension. A list item whose content starts with [ ] or [x] renders as a checkbox. Strict CommonMark shows the brackets literally.

- [ ] not done
- [x] done
- [X] also done, uppercase works
- [ ] nested tasks work too
  - [x] subtask

Details that matter:

• The space inside the empty box is required. [] is not a task item.
• A space between the box and the text is required. - [x]done renders literally.
• Only list items can be tasks. A task marker in a paragraph is plain text.
• On GitHub, checkboxes in an issue or PR body are clickable and editing them rewrites the source.

Where they are supported: GitHub, GitLab, Gitea, Obsidian, VS Code preview, most static-site generators. Where they are not: plain CommonMark, and older Pandoc without the extension enabled.

Starting a Line With a Number

A line beginning with a number and a period becomes an ordered list, even when you meant a year or a version.

1984. It was a cold April morning.

That renders as a one-item list starting at 1984. Escape the period to prevent it.

1984\. It was a cold April morning.

The same escape applies to a paragraph that has to start with -, *, +, or #.

\- not a list item
\# not a heading