Lists in Markdown
Learn how to create ordered, unordered, and nested lists in your Markdown documents
Creating Lists in Markdown
Lists are an essential part of organizing content in your Markdown documents. Markdown supports three types of lists: unordered (bulleted) lists, ordered (numbered) lists, and task lists. Each type has its own syntax and use cases. Lists can be combined with other elements like links, images, and code blocks. For more structured data, consider using tables. You can also use our List Generator tool to easily create list syntax.
Unordered Lists
Unordered lists are created using asterisks (*), plus signs (+), or hyphens (-) as bullet points. Each list item starts on a new line with a bullet point followed by a space.
* Item 1
* Item 2
* Item 3
+ First item
+ Second item
+ Third item
- Apple
- Banana
- OrangeAll three of these methods will produce the same output when rendered:
- Item 1
- Item 2
- Item 3
- First item
- Second item
- Third item
- Apple
- Banana
- Orange
Note: For consistency, it's best to use the same symbol throughout your document for unordered lists.
Ordered Lists
Ordered lists use numbers followed by periods. The numbers don't have to be in numerical order, but the list will always start with the first number you use.
1. First item
2. Second item
3. Third item
1. Item one
1. Item two
1. Item three
8. Start with 8
9. Continue with 9
10. End with 10When rendered, these will appear as:
- First item
- Second item
- Third item
- Item one
- Item two
- Item three
- Start with 8
- Continue with 9
- End with 10
Notice that in the second example, even though we used "1." for each item, Markdown automatically increments the numbers. In the third example, the list starts with 8 because that's the first number we used.
More List Examples
Nested Lists
You can create nested lists by indenting list items with spaces or tabs. Most Markdown processors require at least two spaces or one tab for each level of nesting.
* Main item 1
* Sub item 1.1
* Sub item 1.2
* Main item 2
* Sub item 2.1
* Sub-sub item 2.1.1
* Sub-sub item 2.1.2
* Sub item 2.2
* Main item 3When rendered, this will appear as:
- Main item 1
- Sub item 1.1
- Sub item 1.2
- Main item 2
- Sub item 2.1
- Sub-sub item 2.1.1
- Sub-sub item 2.1.2
- Sub item 2.2
- Sub item 2.1
- Main item 3
You can also mix ordered and unordered lists in nested lists:
1. First item
* Sub-bullet
* Another sub-bullet
2. Second item
1. Sub-number one
2. Sub-number two
3. Third itemTask Lists
Many Markdown processors also support task lists (or checklist), which are lists with checkboxes. You create these by using a hyphen followed by square brackets with either a space (unchecked) or an x (checked), and then a space and the task description.
- [ ] Task 1 (unchecked)
- [x] Task 2 (checked)
- [ ] Task 3
- [ ] Subtask 3.1
- [x] Subtask 3.2
- [x] Task 4When rendered, this will appear as a list with checkboxes:
- Task 1 (unchecked)
- Task 2 (checked)
- Task 3
- Subtask 3.1
- Subtask 3.2
- Task 4
Note: Task lists are part of GitHub Flavored Markdown and may not be supported in all Markdown processors.
Lists with Paragraphs
If you need to add paragraphs or other elements within a list item, indent them with at least one space or tab to align with the content above.
* First item with a single paragraph
* Second item with multiple paragraphs
This is a second paragraph within the second list item. Notice the blank line above and the indentation at the beginning of this line.
```
// You can even include code blocks
function example()
```
* Third item with a blockquote
> This is a blockquote inside a list item.
* Fourth item with a nested list
1. First nested item
2. Second nested itemThe key to including paragraphs, code blocks, blockquotes, or other elements within list items is to:
- Insert a blank line after the list item
- Indent the additional content by at least one space or tab
- Add another blank line before the next list item
Best Practices for Lists
Consistency is Key
When creating lists in your Markdown documents, follow these best practices for better readability and compatibility:
- Use consistent markers - Stick to one type of bullet point (*, +, or -) for unordered lists throughout your document.
- Maintain proper indentation - Use consistent spacing for nested lists (typically 2 or 4 spaces per level).
- Add blank lines - Insert blank lines before and after lists for better readability and to ensure proper rendering.
- Avoid mixing list types unnecessarily - While you can mix ordered and unordered lists, do so only when it makes logical sense for your content structure.
- Start ordered lists with 1 - Even though Markdown will render correctly regardless of the starting number, it's best practice to start with 1 for better readability in the source.
Common Mistakes to Avoid
Incorrect Spacing
*No space after the asterisk * Correct spacing * Too many spacesAlways use exactly one space after the list marker for proper rendering.
Breaking List Continuity
1. First item 2. Second item This text breaks the list 3. Third itemAvoid inserting regular text between list items without proper formatting. If you need to add text, indent it properly or use paragraphs within list items.
Inconsistent Indentation
* Main item * Sub-item with 2 spaces * Sub-sub-item with 4 spaces * Inconsistent indentation with 3 spacesMaintain consistent indentation (typically 2 or 4 spaces) for each level of nesting.
Interactive Markdown List Generator
Practice creating different types of lists with our interactive list generator. Try both ordered and unordered lists!
* First item
* Second item
* Third item- First item
- Second item
- Third item
Additional Resources
Official Markdown Specifications
Learn more about Markdown list syntax from the original specification and popular implementations.
Related Markdown Elements
Explore other Markdown elements that work well with lists:
Useful Tools
Check out these tools to help you work with Markdown lists more efficiently: