Lists

Markdown gives you three list shapes: numbered, bulleted, and GFM task lists. Each one nests, each one holds block content, and you can mix them freely. When a numbered sequence needs its own visual treatment, reach for the Steps component instead.

Quick Start

A numbered list needs nothing but 1. in front of each line.

1. Clone the repository
2. Install dependencies
3. Start the dev server

1. Clone the repository
2. Install dependencies
3. Start the dev server

Adding Options

Nesting

Indent a bullet by two spaces and it nests under the line above it. Mixing shapes is fine, and a nested list can be ordered under a bulleted parent or the other way round.

• Supports nested lists
  • Second level
    1. Ordered inside bulleted
    2. Numbering restarts per level
• Back to first level

- Supports nested lists
  - Second level
    1. Ordered inside bulleted
    2. Numbering restarts per level
- Back to first level

Indent to the first character after the parent's marker: two spaces after -, three after 1..

Markers and start numbers

The first number you write sets where the list starts, and the rest renumber from there no matter what you type.

3. Third item, because the list opens at three
4. Fourth
5. Fifth

3. Third item, because the list opens at three
4. Fourth
5. Fifth

Only the first number matters. Bulleted lists accept -, *, or +, and ordered lists accept . or ) after the number. Every combination renders the same, and Prettier rewrites them all on save, so these have no live form:

* star bullet          same output as -
+ plus bullet          same output as -
1) paren delimiter     same output as 1.
1. one                 renumbered from the first item
1. two                 renders as 2, not 1

Switching the marker mid-list starts a second list rather than continuing the first.

Advanced

Task lists

- [ ] and - [x] render a disabled checkbox in front of the item. An uppercase [X] counts as checked, the space inside the brackets is required, and tasks work at the top level or nested under a numbered parent.

• Install dependencies
• Copy the example environment file
• Set the site password variable

1. Set up the project
   • Read the quickstart
   • Run the setup script
2. Write the first page
   • Create app/guides/index.mdx
   • Add title and description frontmatter

- [x] Install dependencies
- [x] Copy the example environment file
- [ ] Set the site password variable
 
1. Set up the project
   - [x] Read the quickstart
   - [ ] Run the setup script
2. Write the first page
   - [x] Create `app/guides/index.mdx`
   - [ ] Add title and description frontmatter

Write - [] with no space and you get a plain bullet with two brackets in it.

Block content inside an item

Indent anything to the item's content column and it belongs to that item: extra paragraphs, code fences, blockquotes, even tables.

1. Install the dependencies

   The lockfile is the authority here, so use npm ci on a clean checkout.

   Bash

   BashCopy

   npm ci

2. Check the result

   A failed install leaves node_modules half-written. Delete it and retry.

   Command	When
   npm ci	Clean checkout
   npm i	Adding packages

1. Install the dependencies
 
   The lockfile is the authority here, so use `npm ci` on a clean checkout.
 
   ```bash
   npm ci
   ```
 
2. Check the result
 
   > A failed install leaves `node_modules` half-written. Delete it and retry.
 
   | Command  | When            |
   | -------- | --------------- |
   | `npm ci` | Clean checkout  |
   | `npm i`  | Adding packages |

Tight and loose spacing

Without blank lines a list stays tight, and the items sit close together.

• Tight item one
• Tight item two

- Tight item one
- Tight item two

Put a blank line between the items and the list turns loose. Each item gets wrapped in a paragraph, which is where the extra vertical space comes from.

• Loose item one

• Loose item two

- Loose item one
 
- Loose item two

Looseness belongs to the list, not to the item. One blank line anywhere in a ten-item list spaces out all ten.

Options