Markdown Lists

Markdown lists organize related information into a clear, structured format. Instead of writing long paragraphs, you can group ideas into bullet points, numbered steps, or checklists that are easier to read and scan.

Markdown supports four main list types:

• Unordered lists – Display items with bullets when the order doesn't matter.
• Ordered lists – Number each item for steps or instructions that follow a sequence.
• Nested lists – Group related items under a parent list.
• Task lists – Create interactive checklists supported by GitHub Flavored Markdown and many modern editors.

Each list type is designed for a different purpose. Unordered lists work well for collections of related items, ordered lists guide readers through a sequence, nested lists add hierarchy, and task lists help track progress. For spacing and blank lines between lists, see the Markdown Paragraphs guide.

Use an unordered list when the order of items doesn't matter. Markdown supports three bullet markers: a hyphen (-), an asterisk (*), and a plus sign (+). All three produce the same result in most Markdown editors.

Example

- Markdown
- GitHub
- Documentation
- README

Output

Markdown also accepts asterisks (*) and plus signs (+) as bullet markers. Most teams use hyphens because they keep documentation consistent, especially in larger projects where multiple people edit the same files.

* Markdown
* GitHub
* Documentation

or

+ Markdown
+ GitHub
+ Documentation

Use an ordered list when the sequence of items matters. Markdown numbers each item automatically, making ordered lists ideal for tutorials, installation guides, recipes, checklists, and other step-by-step instructions.

Example

1. Install Git
2. Clone the repository
3. Open the project
4. Run the application

Output

Ordered lists work best when readers need to follow actions in a specific order. They're commonly used for software installation guides, onboarding instructions, recipes, troubleshooting steps, and other sequential workflows.

Lazy numbering#

You don't have to update every number yourself. Most Markdown editors automatically display the correct sequence, even if every list item starts with 1.. This makes it much easier to insert, remove, or reorder steps later.

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

Output

This approach saves time when editing long documents because you can move or insert steps without renumbering the entire list manually.

Nested lists let you group related items under a parent list item. They make long documents easier to organize and help readers understand the relationship between topics.

Example

- Programming Languages
  - JavaScript
  - Python
  - Go
- Frameworks
  - React
  - Next.js

Output

Indent child items consistently using two or four spaces, depending on the Markdown editor or renderer you're using. Mixing indentation styles can cause nested lists to display incorrectly.

You can combine ordered and unordered lists in the same document. This approach works well when a numbered process includes supporting notes or grouped items.

Example

1. Install the project
   - Clone the repository
   - Install dependencies
2. Start the application

Output

Mixed lists are commonly used in technical documentation, onboarding guides, and software setup instructions where each step includes additional details.

Task lists extend standard Markdown by adding interactive checkboxes. They're widely used for project planning, issue tracking, release checklists, documentation, and personal TODO lists in GitHub and other Markdown editors that support GitHub Flavored Markdown (GFM).

💡 Want to learn more? See the complete Markdown Task Lists guide for nested checklists, ordered task lists, interactive GitHub checkboxes, and troubleshooting tips.

Example

- [x] Install dependencies
- [x] Configure project
- [ ] Deploy application

Output

Task lists make it easy to track completed and pending work. They're commonly used in GitHub repositories, project documentation, sprint planning, release checklists, and personal task management.

Create checklists faster with the Markdown Task List Generator, or test list formatting in the Markdown Editor before adding it to your documentation.

Markdown lists can be placed inside blockquotes to organize quoted notes, callouts, discussions, or documentation examples without losing the quote formatting.

Example

> Project Checklist
>
> - Install Node.js
> - Install dependencies
> - Run the server

Output

This pattern is commonly used in documentation, release notes, tutorials, and technical guides where quoted information also contains a checklist or bullet points.

List items can include fenced code blocks when each step requires a command or code example. Leave a blank line before the code block and indent it correctly so it remains part of the list item.

Example

1. Install the package

   ```bash
   npm install
   ```

2. Start the development server

   ```bash
   npm run dev
   ```

Output

This format is commonly used in installation guides, tutorials, and technical documentation where readers need to run commands step by step. For more details about fenced code blocks, language identifiers, and syntax highlighting, see the Markdown Code Blocks guide.

Well-formatted lists are easier to read and maintain. Following a few simple practices keeps your Markdown documents consistent across editors, repositories, and documentation projects.

• Keep list items concise. Long bullet points are harder to scan and reduce readability.
• Choose the right list type. Use unordered lists for related items, ordered lists for sequences, and task lists for checklists.
• Indent consistently. Consistent spacing keeps nested lists rendering correctly across different Markdown editors.
• Stick to one bullet style. Using the same marker throughout a document improves readability and keeps formatting consistent.
• Review before publishing. Check that numbering, indentation, and nested items display as expected.

Most Markdown list formatting problems are caused by inconsistent bullets, incorrect indentation, or using numbered lists where order isn't important. These simple fixes help your lists render correctly across different Markdown editors.

Mixing Bullet Styles#

Choose one bullet marker and use it consistently throughout the document. Although Markdown supports hyphens (-), asterisks (*), and plus signs (+), mixing them in the same list makes documentation look inconsistent.

Avoid

- Item One
* Item Two
+ Item Three

Better

- Item One
- Item Two
- Item Three

Incorrect Indentation#

Nested lists depend on consistent indentation. If child items aren't indented correctly, they may appear as separate lists instead of nested items.

Incorrect

- Item
- Child Item

Correct

- Item
  - Child Item

Using Ordered Lists Incorrectly#

Use numbered lists only when the sequence matters. If the order isn't important, unordered lists are usually easier to read and maintain.

Incorrect

1. Apple
2. Banana
3. Orange

Better

- Apple
- Banana
- Orange

Most modern Markdown editors support unordered, ordered, and nested lists. Task list support depends on whether the editor implements GitHub Flavored Markdown (GFM), so behavior may vary between platforms.

Clear, consistent lists are easier to read than long blocks of text. Before publishing, take a quick look through your document to make sure list formatting is consistent from top to bottom.

• Keep each list item focused on a single idea.
• Use the same bullet style throughout the document.
• Indent nested items consistently.
• Choose ordered lists only when the sequence matters.
• Split long paragraphs into lists when it improves readability.