How to Create Ordered, Unordered, and Nested Lists in Markdown

Lists are one of the most common elements you'll write, whether you're drafting a README, a changelog, or a set of notes. A well-structured markdown list keeps content scannable, readable, and easy to maintain. In this guide we'll cover unordered (bullet) lists, ordered (numbered) lists, how to build a clean nested list markdown layout, multi-paragraph items, task lists, and the most common mistakes that break formatting. If you want to try any of these examples as you read, paste them into the online editor and watch them render instantly.

Unordered (Bullet) Lists

Unordered lists are your go-to for items where sequence doesn't matter. Markdown gives you three interchangeable markers: the hyphen -, the asterisk *, and the plus sign +. All three render as the same bullet.

- Apples
- Oranges
- Bananas

You can also use * or +:

* Draft the outline
* Write the first section
* Review and revise

+ Run the tests
+ Commit the changes
+ Open a pull request

The single rule: pick one marker and stick with it within a list. Mixing -, *, and + in the same list isn't an error, but it makes your source harder to read and some linters will flag it. For a broader overview of where lists fit into the language, see our introduction to Markdown.

Ordered (Numbered) Lists

Ordered lists are for sequences — steps, rankings, or anything where order matters. Start each line with a number followed by a period and a space.

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

Here's a detail that surprises many newcomers: the actual numbers don't have to be sequential. Most renderers (and GitHub Flavored Markdown in particular) will renumber the list automatically based on position. Many writers therefore type 1. for every item, which makes it trivial to reorder entries later without renumbering:

1. First step
1. Second step
1. Third step

This renders as 1. 2. 3. You can also start from a number other than one — 3. will begin the list at 3 — though support for the starting value varies slightly across renderers.

For a full reference of list markers and other syntax at a glance, grab our Markdown cheat sheet.

Comparison of List Markers

Marker	List type	Notes
-	Unordered	Most common; widely recommended for consistency
*	Unordered	Valid; common in older docs
+	Unordered	Valid; less common today
1.	Ordered	The leading number sets the start value
- [ ] / - [x]	Task list	GFM extension; renders checkboxes
* (paired)	Loose list	Two * can wrap emphasis inside list items

Nested Lists in Markdown

Indentation is everything when you want a nested list markdown structure. To nest a list under an item, indent the child items by either 2 or 4 spaces (pick one and be consistent across the document) so they align beneath the parent's text. Most style guides recommend 2 or 4 spaces — the key word is consistency.

- Fruits
  - Apples
    - Fuji
    - Granny Smith
  - Oranges
- Vegetables
  - Carrots
  - Spinach

Renders as:

• Fruits
  • Apples
    • Fuji
    • Granny Smith
  • Oranges
• Vegetables
  • Carrots
  • Spinach

You can also mix list types — for example, ordered steps nested under a bullet:

- Setup checklist
  1. Install Node.js
  2. Clone the repo
  3. Run `npm install`
- Deployment
  1. Build the project
  2. Deploy to your host

A reliable way to think about indentation: align the child marker directly under the first character of the parent item's text (i.e., one level in, matching your chosen 2- or 4-space convention). Misaligned children are the number-one cause of lists that won't nest properly.

Lists with Multiple Paragraphs and Long Items

Sometimes a single bullet needs to carry more than one paragraph, or a code block, or a sub-list. To add another paragraph to the same list item, indent the continuation by the same amount as the list content (typically 2 spaces for - markers, or 4 to match a 4-space style):

- First item.

  Second paragraph of the first item.

- Second item, with a code sample:

  ```js
  console.log('lists are great')

The blank line before the continuation paragraph is required — without it, the text gets folded into the previous line as a "soft wrap" rather than treated as a new paragraph. Code blocks inside list items follow the same indentation rule: indent the opening and closing fences to match the item's content level.

## Task Lists (Checkboxes)

GitHub Flavored Markdown adds a special bullet for checklists: `- [ ]` for an open item and `- [x]` for a completed one.

```md
- [x] Draft the outline
- [x] Write the examples
- [ ] Proofread
- [ ] Publish

Task lists are hugely useful in issues, PRs, and project READMEs. Because they have their own quirks (like rendering behavior and nested checkboxes), we cover them in depth in our Markdown task lists guide. For more GFM-specific features in general, see the GitHub Flavored Markdown guide.

Common Mistakes and How to Fix Them

Most broken lists come down to two things: inconsistent indentation and missing blank lines.

1. Mixed indentation depths. If you nest one level at 2 spaces and another at 4, the renderer may flatten or misplace items. Pick a depth (2 or 4 spaces) and apply it everywhere.

2. Tabs instead of spaces. Tabs technically work in many parsers, but mixing tabs and spaces in the same document is the classic recipe for broken nesting. Convert tabs to spaces for safety.

3. No blank line before a list. Some renderers need a blank line between a paragraph and the list that follows it, otherwise the list can be absorbed into the paragraph. Always leave an empty line before a list (and usually after one too).

4. Trailing spaces on the marker line. Two or more trailing spaces create a hard line break, which can disrupt list rendering. Trim trailing whitespace.

5. Inconsistent markers. Switching between - and * in the same list won't error, but it signals disorder. Standardize on one.

<!-- Wrong: no blank line, mixed markers, sloppy indentation -->
Text directly above
- Item one
   * Item two with 3 spaces
   - Item three

<!-- Right: blank line, single marker, consistent 2-space nesting -->

- Item one
  - Item two
  - Item three

Frequently Asked Questions

How many spaces should I use to indent a markdown list?

Either 2 or 4 spaces works — the important thing is consistency. Most modern style guides recommend 2 spaces for readability, but 4 is equally valid. Pick one and configure your editor to insert spaces (not tabs) on the Tab key.

Do I need to type the actual numbers in an ordered list?

No. Renderers renumber ordered lists based on position, so typing 1. for every item is a perfectly valid and popular technique — it makes reordering items trivial. The only number that matters is the first one, which sets the list's starting value.

Can I mix ordered and unordered lists?

Yes. You can nest an ordered list inside a bullet list or vice versa, as long as the indentation lines up under the parent item's text. Mixing list types within the same level (e.g., a 1. directly after a - on the same level) is generally discouraged, since renderers may treat them as separate lists.

Why won't my nested list render correctly?

Almost always because of indentation. Double-check that child items are indented to align with the parent item's text, that you aren't mixing tabs and spaces, and that there's a blank line before the list. When in doubt, paste the block into the editor and adjust until it nests correctly.

Lists are simple, but the details — consistent markers, consistent indentation, blank lines between blocks — are what separate clean, maintainable Markdown from formatting that breaks the moment you edit it. Master these conventions and every document you write, from a quick checklist to a full README, will render exactly the way you intend.