How to Create Lists in Markdown
For a bullet list, start each line with a dash, asterisk, or plus sign followed by a space: - item. For a numbered list, use a number, a period, and a space: 1. item. Nest items by indenting them under their parent.
Platform Support
Pick one bullet marker and stick with it — dashes are the most common convention. The choice is not purely cosmetic: in CommonMark, switching markers (from - to *) mid-list actually starts a new list, which can introduce unexpected vertical spacing. Ordered lists are more forgiving than they look: the numbers you type mostly do not matter, because renderers renumber sequentially from the first item. Writing 1. for every item is a popular trick — inserting or reordering items never requires renumbering, and the output is identical.
Nesting is where lists break most often. A nested item must be indented to align with the content of its parent, not just "some spaces". For a bullet (- item), the content starts at column 2, so two spaces of indent works; for an ordered item (1. item), the content starts at column 3, so nested items under it need three spaces. Tabs and inconsistent indent levels are the root cause of most "my nested list renders flat" bugs. When in doubt, four spaces per level works under both kinds of parent in most renderers.
Markdown distinguishes tight lists (no blank lines between items, rendered compactly) from loose lists (blank lines between items, each item wrapped in a paragraph with more spacing). Mixing the two in one list makes the whole list loose. To put multiple paragraphs, a code block, or a blockquote inside one list item, indent that content to the item's content column — a fenced code block inside 1. needs three spaces of indent, or it will terminate the list and reset your numbering to 1.
Two interaction gotchas: a line starting with a number and a period (like "1999. was a good year") at the start of a paragraph will accidentally begin an ordered list — escape the period as 1999\. to prevent it. And a list needs a blank line before it when it follows a paragraph; without one, many renderers (including CommonMark in some positions) fold the would-be list items into the paragraph above.
Examples
- Item 1
- Item 2
- Nested item
- Another nested
- Item 3- Item 1
- Item 2
- Nested item
- Another nested
- Item 3
Create bullet lists using dashes, asterisks, or plus signs.
- Item
- Item- Item
- Item
* Item
* Item- Item
- Item
+ Item
+ Item- Item
- Item
1. First item
2. Second item
3. Third item
1. Nested item
2. Another nested- First item
- Second item
- Third item
- Nested item
- Another nested
Create numbered lists using numbers followed by periods.
1. First step
1. Second step
1. Third step- First step
- Second step
- Third step
Renderers number sequentially regardless of the digits you type, so all 1. is maintenance-free.
1. Gather requirements
- Interview users
- Review tickets
2. Write the spec- Gather requirements
- Interview users
- Review tickets
- Write the spec
Bullets nested under an ordered item need 3 spaces to align with the parent content.
1. First item
This paragraph belongs to the first item.
2. Second itemFirst item
This paragraph belongs to the first item.
Second item
Indent continuation content to the item content column to keep numbering intact.
Common Mistakes
-item (no space after the marker)- itemThe space between the marker and the text is required. -item renders as a literal line of text.
Nesting with a single space of indentIndent nested items to the parent content column (2 spaces under -, 3 under 1.)Insufficient indentation flattens the nested item to the top level. Align it with where the parent item text starts.
An unindented code block between numbered itemsIndent the code block 3+ spaces so it belongs to the list itemUnindented block content ends the list — the next numbered item restarts at 1.
Platform Notes
GitHub
Full CommonMark list behavior, including auto-renumbering and ordered lists that start at any number (5. starts the list at 5).
Discord
Supports - bullets and 1. numbered lists with limited nesting. Long messages with deep nesting often render inconsistently.
Slack
No Markdown list parsing in messages — typed hyphens stay literal, though the rich-text editor offers its own list buttons.
Notion
Typing - or 1. followed by a space converts to native list blocks. Nesting is handled with Tab rather than spaces.
Frequently Asked Questions
How do I make a bullet list in Markdown?
Start each line with a dash, asterisk, or plus sign followed by a space: - item one. Dashes are the most common convention; whichever you choose, stay consistent within a list.
Why is my numbered list numbering wrong?
Usually something unindented (a paragraph or code block) between items ended the list, restarting it at 1. Indent continuation content to the item content column to keep one continuous list.
How do I nest a list inside another list?
Indent the nested items to align with the parent item's text: 2 spaces under a - bullet, 3 spaces under a 1. ordered item. Four spaces per level also works in most renderers.
Do the numbers in an ordered list matter?
Only the first one. Renderers number sequentially from the first item's value, so 1./1./1. renders as 1, 2, 3. Starting with 5. begins the list at 5 in CommonMark.
How do I add a code block or paragraph inside a list item?
Indent it to the item's content column (3+ spaces under an ordered item) with a blank line before it. Unindented blocks end the list.
Related Syntax
Task Lists
Learn how to create task lists (checkboxes) in Markdown with - [ ] and - [x] syntax.
Code Blocks
Learn Markdown code formatting: inline code with backticks, fenced code blocks with syntax highlighting, nesting backticks, and indented code blocks.
Line Breaks
Learn how to add line breaks in Markdown: two trailing spaces, the <br> tag, or a backslash.