MarkdownViewer

Markdown Lists: Bullets, Numbers and Nesting

Lists are the most-used Markdown element and the one with the most surprising edge cases: numbers that ignore what you type, nesting that depends on indentation, and blank lines that quietly end a list. This guide covers the syntax and the rules behind it.

Unordered and ordered lists

An unordered list uses a dash, asterisk or plus as the bullet; the three are interchangeable. An ordered list uses a number and a period — and the numbers are renumbered automatically, so `1.` on every line still renders as 1, 2, 3. Use whatever number helps you read the source.

  1. `- item` — the commonest bullet
  2. `* item` and `+ item` — equivalent
  3. `1. item` — ordered; the actual numbers do not matter

Nesting

Indent a nested item by two to four spaces under its parent. Keep the indentation consistent through the whole list, and put a blank line before a code block inside a list item — otherwise the code is treated as part of the list text.

The rules that trip people up

A blank line between items creates a 'loose' list with paragraph spacing; no blank lines makes a tight list. Starting a new paragraph inside an item needs a blank line plus indentation. And switching between bullet characters without changing indentation can start a new list rather than continuing the same one.

Task lists

GitHub-Flavoured Markdown adds checkboxes: `- [ ]` for an open task and `- [x]` for a done one. They render as interactive checkboxes on GitHub and as static boxes elsewhere.

Frequently Asked Questions

Why does my numbered list restart at 1?
Because a blank line or a change in indentation can end one list and begin another. Remove the blank lines or align the indentation to keep it as a single list.
Can I mix bullets and numbers?
Yes, as separate lists or as nested levels — an ordered list nested under a bullet, or vice versa. Each level can use a different style.
How do I indent a list correctly?
Two spaces is enough for most renderers, four is the classic standard. The important thing is consistency so a renderer sees the same nesting depth on every item.
Why is my code block showing as list text?
You probably did not leave a blank line before the fenced block, and the indentation did not mark it as nested content. Add a blank line and indent the fence to match the item.

Related Markdown Tools

Markdown ViewerMarkdown Cheat SheetHow to Write MarkdownMarkdown SyntaxAll Markdown Tools