Lists and Nesting

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Write bullet, numbered and task lists that stay together. Repair a setup guide whose nested list collapsed, learn the indent rule, keep notes and code inside a step, and pick the list type an AI agent will read correctly.

The Setup Guide That Collapsed

Asha writes a setup guide for the order-support app. She wants two steps, with two things to install under the first step. In her editor, it looks right:

A setup guide that went flat

1. Install the tools
 - Node 20
 - npm
2. Start the app

Look at the Rendered tab. "Node 20" and "npm" are not inside step 1. They became a separate bullet list between the steps. Open the HTML tab: there are three lists, not one. Step 2 ended up in a list of its own.

The cause is one missing space. In this lesson, you will learn exactly how much to indent, and the other rules that keep lists together.

In simple words: a list item belongs inside another item only when it lines up under that item's text.

TL;DR

• A bullet list uses -, * or + and a space at the start of each line. Pick - and use it everywhere.
• A numbered list uses a number, a full stop and a space: 1. . The first number sets where counting starts.
• To put a list inside a list, indent the inner items so they line up with the text of the outer item. That is 2 spaces under - and 3 spaces under 1. .
• Anything that is not indented ends the list.
• - [ ] and - [x] make a task list on GitHub.

A Real-World Example

Think about a recipe.

The ingredients are a list. The order does not matter: you can fetch the eggs before the flour. The steps are a numbered list. The order matters: you cannot bake before you mix.

Some steps have small parts. "Prepare the pan" might have "grease it" and "line it with paper" written under it, a little to the right. That indent tells you they belong to that step.

Markdown lists work the same way. Bullets for things in any order. Numbers for things in a fixed order. An indent for parts that belong to one item.

What You Will Learn

In this lesson, you will learn:

1. How to write bullet lists and numbered lists.
2. How the first number sets the count.
3. How far to indent a list inside a list.
4. How to keep text and code inside a list item.
5. How to write a task list.
6. Which list to use when an AI agent reads it.

Cheat Sheet

Every kind of list

Bullets:

- Refunds
- Shipping
- Returns

Numbers:

1. Open the order
2. Check the receipt
3. Approve the refund

A list inside a list:

- Install the tools
  - Node 20
  - npm
- Start the app

A task list:

- [x] Fix refund rounding
- [ ] Add order search

Change the text, the marks and the spaces on the left. Watch how the right side changes.

Bullet Lists

Three Marks, One Result

A bullet list is a list where the order does not matter. Start each line with -, * or +, then a space.

Three marks, three lists

- Refunds
- Shipping

* Refunds
* Shipping

+ Refunds
+ Shipping

All three look the same on the page. Open the HTML tab: each one is a ul, which stands for unordered list. Each item is an li, a list item.

Do Not Mix the Marks

There is a catch. If you change the mark in the middle of a list, Markdown starts a new list.

One list, or three?

- Refunds
* Shipping
+ Returns

This looks like one list with three items. Open the HTML tab. It is three separate lists with one item each. On the page, the gaps between them can look odd.

Pick one mark and use it in every file. Most teams use -.

Numbered Lists

Numbers and the First Number

A numbered list is a list where the order matters. Start each line with a number, a full stop and a space. A closing bracket works too: 1).

The first number sets the count

1. Open the order
1. Check the receipt
1. Approve the refund

A list that starts at 3:

3. Third step
4. Fourth step

The first list uses 1. on every line, but the page shows 1, 2, 3. Markdown counts for you. Only the first number matters. The second list starts at 3, because its first number is 3.

Many people write 1. on every line on purpose. Then you can add or remove a step without renumbering the rest. Open the HTML tab: a numbered list is an ol, an ordered list.

When a Number Is Not a List

A line that starts with a number and a full stop becomes a list item, even when you did not mean it.

A year that became a list

2023. A great year for the team.

2023\. A great year for the team.

The first line turned into a list that starts at 2023. To stop that, put a backslash before the full stop, like the second line. The backslash tells Markdown "this is just a full stop".

A List Inside a List

The Indent Rule

A nested list is a list inside a list item. To nest an item, indent it so it lines up with the text of the item above. Not with the mark — with the text.

• Under - Install, the text starts 2 characters in. So indent the inner items by 2 spaces.
• Under 1. Install, the text starts 3 characters in. So indent the inner items by 3 spaces.

Line up with the text

- Install the tools
  - Node 20
  - npm
- Start the app

1. Install the tools
   - Node 20
   - npm
2. Start the app

Both lists nest correctly. Open the HTML tab: the inner ul sits inside the first li.

Now go back to the box at the top of the lesson. Add two more spaces in front of - Node 20 and - npm, so each has three. The guide joins up into one list.

How Deep to Go

You can nest a list inside a nested list. Each level indents again. But two levels is usually enough. Deeper lists are hard to read, both as raw text and on the page.

If you need three levels, the content probably wants headings instead.

Text and Code Inside a List Item

Anything Not Indented Ends the List

A list ends at the first line that is not part of it. A paragraph with no indent breaks the list in two.

A note that broke the numbering

1. Install the tools

Do this before anything else.

2. Start the app

The note is not part of step 1, so the list ended there. Step 2 starts a new list, and its number came from the 2. you typed. If you had typed 1. on every line, the page would show "1" twice.

To keep the note inside step 1, indent it to line up with the step's text, 3 spaces:

The note inside the step

1. Install the tools

   Do this before anything else.

2. Start the app

Now there is one list with two steps, and the note belongs to step 1.

Code Inside a Step

Setup guides often have a command inside a step. The same rule applies: indent the whole code block to line up with the step's text. You will learn about code blocks in a later lesson. For now, just look at the indent.

A command inside a step

1. Install the packages:

   ```bash
   npm install
   ```

2. Start the app:

   ```bash
   npm start
   ```

Each command sits inside its step. Delete the three spaces in front of the first code block and watch the list break in two.

Tight and Loose Lists

You may notice that some lists have more space between items. That is because of blank lines.

• A list with no blank lines between items is tight. Items sit close together.
• A list with a blank line between items is loose. Each item is wrapped in a paragraph, so it gets more space.

Both are fine. Just do not mix them in one list, or the spacing looks uneven.

Task Lists

A task list is a list of things to do, with a checkbox for each. Write [ ] for an open task and [x] for a done task, right after the bullet.

A release checklist

- [x] Fix refund rounding
- [x] Add order search
- [ ] Update the help centre
- [ ] Tell the support team

Now switch the box to CommonMark. The checkboxes are gone, and the page shows [ ] and [x] as text. Task lists are part of GitHub Flavored Markdown, not CommonMark. You will learn more about this difference in the Markdown Flavors lesson.

Lists and AI Agents

AI agents read lists in the same way people do, so the type of list carries meaning.

If your steps are bullets, an agent may run them in any order. If your rules are numbered, an agent may think rule 1 is more important than rule 5. Choose the list type that says what you mean.

Where Lists Are Used

• README files: install steps as a numbered list, features as bullets.
• Release notes: one bullet per change.
• Pull requests and issues: task lists for what is left to do.
• AI agent files: a bullet list of rules, a numbered list of commands to run in order.
• Specs: a task list of acceptance checks.

Common mistakes

Quick Check

Exercises

What to Remember

• Bullets (-) are for things in any order. Numbers (1.) are for steps in a fixed order.
• Use one bullet mark everywhere. A new mark starts a new list.
• Only the first number counts. Writing 1. on every line is fine.
• To nest, line up with the text above: 2 spaces under - , 3 spaces under 1. .
• Indent notes and code that belong to a step. Anything not indented ends the list.
• - [ ] and - [x] make a task list on GitHub.

Further Reading

• CommonMark: list items: the exact indent rules.
• GitHub Flavored Markdown: task list items: how checkboxes work.
• GitHub Docs: lists: lists and nested lists on GitHub.

Next: Links and Images, where you link to other files and headings, add pictures with good alt text, and fix the broken links in the project's docs.