Markdown lists: bullets, numbers, nesting and checkboxes

Ordered lists and lazy numbering

An ordered list is a number, a period, a space, then your text:

1. Preheat the oven to 180C
2. Mix the dry ingredients
3. Fold in the melted butter

Every number after the first is ignored

Here is the part that surprises people. The renderer emits an <ol> and lets the browser count, so this renders as 1, 2, 3 as well:

1. Preheat the oven to 180C
1. Mix the dry ingredients
1. Fold in the melted butter

Writing every item as 1. is a better habit for anything stored in Git, for two reasons:

• Cleaner diffs. Insert a step into a hand-numbered list and every later line changes, so twenty modified lines hide one real edit.
• Less bookkeeping. With all-1. numbering, adding or removing a step touches exactly one line.

Starting at a number other than 1

The first number is respected, so a list can resume where an earlier one stopped:

5. Tag the release
6. Publish the changelog
7. Announce it

That renders starting at 5. One caveat applies in CommonMark and GitHub Flavored Markdown: an ordered list starting at anything but 1 cannot interrupt a paragraph, so it always needs a blank line above it. You can also write 1) instead of 1., and switching delimiter mid-list starts a second list.

Paragraphs, code and quotes inside a list item

A list item can hold any block content: several paragraphs, a fenced code block, a blockquote. The requirement never changes. Leave a blank line, then indent the extra content to the parent's content column.

A second paragraph

- Keep the commit message short.

  The body can be longer, and it belongs to the same
  bullet because it is indented two spaces.

- The next bullet resumes here.

A code block

Indent the fence itself, not just the code. Three spaces here, because the parent is an ordered item:

1. Install the parser:

   ```bash
   npm install marked
   ```

2. Import it in your entry file.

Under-indenting the fence is the classic failure. The code block escapes the list, the list ends, and the next item restarts the numbering at 1. If your steps suddenly reset, check the indentation of the fence just above the reset. There is more on fences in the code blocks reference.

A blockquote

- The specification is blunt about this:

  > A list item can contain any kind of block,
  > including other lists.

Quoted material inside a list follows the marker rules from the blockquotes reference, on top of the indentation above. Tables work the same way, though a table inside a list item usually means the content wants its own section, and the tables reference covers when that is worth it.

Task lists and checkboxes

Task lists are a GFM extension: a normal bullet followed by a bracket pair. An empty pair is unchecked, an x is checked.

- [ ] Draft the release notes
- [x] Bump the version number
- [ ] Tag the release
  - [x] Sign the tag
  - [ ] Push it

The spacing is exact: marker, space, [, then a space or an x, then ], then a space, then the text. -[ ] fails because the marker has no space after it. - [x]Ship it fails because the bracket has none. A capital [X] is fine on GitHub, and nesting works exactly as it does for ordinary bullets.

Where the boxes are actually clickable

Rendering and interactivity are different things. The box appears far more widely than it can be ticked:

• GitHub issues, pull requests, discussions and comments. Clickable for anyone who can edit the item. Ticking one rewrites the underlying Markdown and updates the progress counter.
• A README.md on GitHub or GitLab. Renders, but read-only, because there is nothing to write the change back to.
• Obsidian, VS Code preview and most note apps. Clickable, and the change is saved into your file.
• Static site generators. Usually rendered as disabled inputs.
• Plain CommonMark renderers. No extension at all, so readers see the literal [ ] characters.

Check the GFM reference before you rely on task lists somewhere unfamiliar.

Loose and tight lists: why blank lines change the spacing

Two lists with identical items can render with visibly different spacing. The cause is a blank line you may not have noticed. A tight list has no blank lines between items:

- One
- Two
- Three

It compiles to compact HTML, with the text sitting directly inside each item:

<ul>
  <li>One</li>
  <li>Two</li>
</ul>

A loose list has a blank line somewhere inside it:

- One

- Two
- Three

Now every item is wrapped in a paragraph, and paragraph margins push the items apart:

<ul>
  <li><p>One</p></li>
  <li><p>Two</p></li>
</ul>

Looseness belongs to the whole list

This is the detail that catches people out:

• One stray blank line among fifteen bullets spaces out all fifteen.
• An item containing two paragraphs makes the list loose too.
• That is why a list with explanations under some items always looks airier than you meant.

Neither form is wrong. Tight suits short scannable items, loose suits items of a sentence or more. Choose deliberately and keep the blank lines consistent.

Common mistakes and their fixes

Five mistakes account for almost every list that will not render:

1. No blank line before the list, so the first bullet is absorbed into the paragraph above.
2. No space after the marker, which prints the dash as text.
3. Nesting indented too shallowly under a number, so the child pops back to the top level.
4. An un-indented note between items, which ends the list and renumbers what follows.
5. Mixed markers in one list, which quietly produces several lists with gaps.

Fixing the blank line and the missing space

GitHub's parser lets a bullet list interrupt a paragraph. Python-Markdown, Markdown.pl, many wikis and most older renderers do not, and an ordered list starting at anything but 1 never can. Broken, then fixed:

Shopping list:
- Milk
- Eggs

Shopping list:

- Milk
- Eggs

The missing space is easier to spot, because the broken version renders as literal text, dash and all. Broken, then fixed:

-Milk
-Eggs

- Milk
- Eggs

Fixing indentation under a number

Two spaces is not enough for an ordered parent, so the child pops back out to the top level. Broken, then fixed with three spaces, aligned under the "P" of "Prepare":

1. Prepare the repository
  - Fork it
  - Clone your fork

1. Prepare the repository
   - Fork it
   - Clone your fork

Fixing a note that splits the list

An un-indented paragraph ends the list. What follows starts a new one and renumbers from its own first value. Broken, then fixed by indenting the note so it stays inside item 2:

1. First step
2. Second step

Remember to save your work.

1. Third step

1. First step
2. Second step

   Remember to save your work.

3. Third step

Debugging a list that will not render

Paste the list into the editor and delete items until it renders. The last one you removed is the culprit, and it is nearly always a space, a blank line or an indent.

Blank lines carry real meaning in this format, which what Markdown is designed to do explains. Our Markdown reference card keeps every list form on one page, and the sibling references for links and images cover what people most often put inside list items.