Home/Docs/Markdown Lists

Markdown Lists

Lists are one of the most commonly used Markdown features. They help organize information into clear, readable sections and are widely used in GitHub README files, technical documentation, tutorials, notes, and project checklists.

Markdown supports several types of lists, including unordered lists, ordered lists, nested lists, and task lists. Once you understand how they work, you'll be able to structure documents much more effectively.

This guide explains every type of Markdown list with practical examples, best practices, and common mistakes.

Practice as you read: Open the Markdown Editor to try unordered, ordered, nested, and task lists with live preview, or bookmark the Markdown Cheat Sheet for quick syntax reference.

Open EditorDownload PDF

What are Markdown Lists?

Markdown lists allow you to present information in a structured way.

Instead of writing long paragraphs, you can break content into individual items that are easier to scan and understand.

Markdown supports four common list types:

  • Unordered lists
  • Ordered lists
  • Nested lists
  • Task lists

Each serves a different purpose depending on the type of content you're writing. For paragraph spacing and blank lines, see the Markdown Paragraphs guide — this page focuses only on lists.

Unordered Lists

Unordered lists display items using bullets instead of numbers.

You can create them using a hyphen (-), an asterisk (*), or a plus sign (+).

Example

- Markdown
- GitHub
- Documentation
- README

Output

Rendered Output

  • Markdown
  • GitHub
  • Documentation
  • README

You can also use:

* Markdown
* GitHub
* Documentation

or

+ Markdown
+ GitHub
+ Documentation

Although all three work, most developers prefer using the hyphen (-) because it is cleaner and more consistent.

Ordered Lists

Ordered lists automatically number each item.

Example

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

Output

Rendered Output

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

Ordered lists are useful whenever the order of steps matters.

Examples include installation guides, tutorials, and documentation.

Nested Lists

Nested lists help organize related information under a parent item.

Example

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

Output

Rendered Output

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

Indent child items using two or four spaces, depending on your Markdown editor.

Mixed Lists

Markdown also allows you to combine ordered and unordered lists.

Example

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

Output

Rendered Output

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

Mixed lists are common in technical documentation.

Task Lists (GitHub Flavored Markdown)

Task lists are supported by GitHub and many modern Markdown editors.

Example

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

Output

Rendered Output

  • Install dependencies
  • Configure project
  • Deploy application

Task lists are ideal for project planning, release checklists, and TODO lists.

Try the Markdown Task List Generator to build checklists quickly, or experiment in the Markdown Editor.

Lists Inside Blockquotes

Lists can also be placed inside blockquotes.

Example

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

Output

Rendered Output

Project Checklist

  • Install Node.js
  • Install dependencies
  • Run the server

Lists with Code Blocks

Lists often contain code examples. Keep a blank line before fenced code blocks inside list items.

Example structure

1. Install the package

npm install

2. Start the development server

npm run dev

This format is commonly used in installation guides and documentation.

Best Practices

Follow these recommendations when creating Markdown lists.

  • Keep list items short and descriptive.
  • Use unordered lists for general information.
  • Use ordered lists for step-by-step instructions.
  • Indent nested lists consistently.
  • Keep the same bullet style throughout the document.
  • Use task lists for project tracking.

Consistent formatting makes documentation easier to read.

Common Mistakes

Mixing bullet styles

Avoid

- Item One
* Item Two
+ Item Three

Better

- Item One
- Item Two
- Item Three

Incorrect indentation

Incorrect

- Item
- Child Item

Correct

- Item
  - Child Item

Using ordered lists incorrectly

Don't use numbered lists unless the order actually matters.

Incorrect

1. Apple
2. Banana
3. Orange

Better

- Apple
- Banana
- Orange

Markdown List Compatibility

Platform Unordered Ordered Nested Task Lists
GitHub ✅ ✅ ✅ ✅
GitLab ✅ ✅ ✅ ✅
VS Code ✅ ✅ ✅ ✅
Obsidian ✅ ✅ ✅ ✅
Notion ✅ ✅ ✅ Partial
Discord ✅ ✅ Limited ❌

Tips for Better Lists

Good lists are:

  • Short
  • Consistent
  • Easy to scan
  • Properly indented
  • Grouped logically

Long paragraphs can often be converted into lists to improve readability.

Continue Learning

Continue learning Markdown with these guides:

Available now

Coming soon to MDConvertHub Docs

  • Markdown Code Blocks

The best way to learn Markdown lists is by writing them yourself. Open the Markdown Editor and experiment with unordered lists, numbered lists, nested lists, and task lists in real time.

Frequently Asked Questions

  1. 1

    How do I create a Markdown list?

    Use -, *, or + for unordered lists, and numbers (1., 2., 3.) for ordered lists.

  2. 2

    Which bullet style should I use?

    The hyphen (-) is the most commonly used style and is recommended for consistency.

  3. 3

    Can Markdown lists be nested?

    Yes. Indent child items using spaces to create nested lists.

  4. 4

    Does GitHub support task lists?

    Yes. GitHub Flavored Markdown supports interactive task lists using [ ] and [x].

  5. 5

    Why isn't my nested list working?

    Most formatting issues happen because of incorrect indentation. Make sure child items are indented consistently.