Structuring data in readable formats makes documentation and blog posts much easier to digest. Lists allow you to group related points sequentially or highlight items dynamically. This guide walks you through creating ordered lists, unordered lists, nested lists, and task lists in Markdown, along with spacing rules for clean layouts.
Key Takeaways
- Build unordered lists using dashes (-), asterisks (*), or plus signs (+).
- Build ordered lists using numbers followed by a period (e.g., 1.).
- Nest lists by indenting sub-items to align with the first character after the parent marker (2 spaces for `-`, 3 spaces for `1.`).
- Create interactive task lists with unchecked [ ] and checked [x] syntaxes.
How to Create Unordered Lists in Markdown?
To create an unordered list (bulleted list), start a line with a dash -, asterisk *, or plus sign +. Follow it with a single space and your list item text. Pick one symbol and use it consistently.
- Milk
- Eggs
- BreadAll three markers produce the same visual output:
- Milk
- Eggs
- Bread
The HTML equivalent generated by the parser:
<ul>
<li>Milk</li>
<li>Eggs</li>
<li>Bread</li>
</ul>How to Create Ordered Lists in Markdown?
To create an ordered list (numbered list), start a line with any number followed by a period . and a single space.
1. First Item
2. Second Item
3. Third ItemThis renders sequentially in the browser. The HTML equivalent:
<ol>
<li>First Item</li>
<li>Second Item</li>
<li>Third Item</li>
</ol>You do not need to write numbers sequentially in your raw Markdown code. Even if you use the same number (for example, writing 1. for every single item), the Markdown parser will automatically convert them to a sequential list (1, 2, 3, etc.) on the live page.
1. Setup local environment
1. Install project dependencies
1. Run local dev serverHow to Create Nested Lists?
To create a nested list (a list inside another list), indent the sub-items to line up with the first character of text in the parent item — that’s 2 spaces after a -/*/+ marker, and 3 spaces after a 1.-style marker (the indent width equals the marker’s width, including the space that follows it).
Here is an example of a nested ordered list:
1. Main Item A
2. Main Item B
1. Sub-item B.1
2. Sub-item B.2
3. Main Item CAnd this renders in the browser as:
- Main Item A
- Main Item B
- Sub-item B.1
- Sub-item B.2
- Main Item C
The HTML output maps a nested list inside the parent <li> tag:
<ol>
<li>Main Item A</li>
<li>Main Item B
<ol>
<li>Sub-item B.1</li>
<li>Sub-item B.2</li>
</ol>
</li>
<li>Main Item C</li>
</ol>How to Create Task Lists in Markdown?
Task lists (or checklists) are a GitHub-Flavored Markdown (GFM) extension that lets you format interactive checklists. Start the line with an unordered list marker (- or *), followed by a space, and brackets containing either a space [ ] for an uncompleted task or an x [x] for a completed task.
- [x] Write project draft
- [ ] Implement team review feedback
- [ ] Publish live siteThis compiles into list items with checkboxes:
- Write project draft
- Implement team review feedback
- Publish live site
To prevent rendering bugs, always leave a blank line before starting a list if it immediately follows a paragraph. Some Markdown engines will fail to recognize the list and merge it into the paragraph text otherwise.
Summary Checklist
- Use
-,*, or+for unordered bulleted lists. - Use
1.for auto-numbered ordered lists. - Indent to match the parent marker’s width (2 spaces for
-, 3 for1.) to nest lists. - Format task lists using
[ ]and[x]brackets. - Maintain a blank line before starting any list block.
Frequently Asked Questions
Can I mix ordered and unordered lists in nesting?
Yes! You can nest an unordered list inside an ordered list, or vice versa. Indent the child list to match the parent marker’s width — 2 spaces under a -/*/+ item, 3 spaces under a 1. item — to show parent-child nesting.
Can I add a paragraph inside a list item?
Yes. To add a paragraph inside a list item without breaking the list flow, indent the paragraph to align with the start of the text in the list item — that’s the marker’s width, so 2 spaces for - bullets or 3 spaces for 1. items (4 spaces is a safe default only for two-digit markers like 10.).
Why are my checklist checkboxes not clickable?
By default, standard Markdown task lists render as read-only checkbox inputs in HTML. Making them interactive (clickable by users) requires client-side JavaScript or a backend state manager.
What to Read Next
- Loose vs. Tight Lists in Markdown — Learn why a single blank line changes how your list items render.
- How to Create Links in Markdown — Discover how to link text to web pages and configure anchor links.
Related Articles
Deepen your understanding with these curated continuations.
Autolinks in Markdown: Bare URLs and Emails
Learn the difference between CommonMark's angle-bracket autolinks and GitHub-Flavored Markdown's extended autolinks for bare URLs and email addresses.
Definition Lists in Markdown
Learn the Markdown Extra-style definition list syntax for terms and descriptions, useful for glossaries and API documentation, plus which tooling supports it.
Escaping Special Characters in Markdown
Learn how to escape asterisks, underscores, brackets, and other special characters in Markdown so they display as literal text instead of triggering formatting.
