How indentation works in Markdown
Try it — edit the markdown and watch the preview
Result
Runs entirely in this tab. Open the full editor to work on a real document.
Leading whitespace in Markdown is not decoration. It carries meaning, and the meaning is usually not the one people expect.
Four spaces is a code block
def hello():
Four spaces — or one tab — at the start of a line makes an indented code block. This is why a paragraph you tried to indent came out in a monospace box with a grey background.
There is no syntax for an indented paragraph, because Markdown produces HTML and HTML has no indented paragraph either; it has CSS.
Nesting lists
A child item must be indented past the point where its parent’s text starts:
- Parent
- Child two spaces, because "- " is two characters
1. Parent
1. Child three spaces, because "1. " is three
Under-indenting is the single most common reason a nested list renders flat. Line up the child’s marker with the first letter of the parent’s text and it will always be right.
Continuing an item
A blank line then an indented block keeps it inside the item:
1. First step
A second paragraph belonging to step one.
and a code block inside it
2. Second step
Indent the continuation to the item’s text, not its number. Get it wrong by one space and the paragraph escapes the list.
If you really want an indent
Two options, both slightly grubby:
> Looks indented, and is a blockquote.
Four non-breaking spaces.
The blockquote is honest about what it is and renders everywhere. The
version is literal indentation but needs HTML entities to be allowed,
and it will not wrap the way a real first-line indent would.
If the document is going to a PDF or a Word file, indent it with the stylesheet at that end rather than with characters in the source.
Tabs
A tab counts as four spaces, so a leading tab makes a code block. Tabs nest lists correctly, but editors render tab width differently — two, four, eight — so a file that looks right in yours may look wrong in someone else’s. Spaces are the safer choice in anything shared.
Common questions
- How do I indent a paragraph in Markdown?
- Not with spaces — four of them turns the line into a code block. Use a blockquote for an indented look, or ` ` repeated for a literal first-line indent. Neither is really indentation; Markdown has no syntax for it.
- How many spaces to nest a list?
- Two for bullets, three for numbered lists. The rule underneath is that a child must be indented past where its parent's text begins — `- ` is two characters wide and `1. ` is three, which is where the two numbers come from.
- Why did my nested list render flat?
- Under-indentation, almost always. One space is not enough for a bullet and two is not enough under a number, so the child is read as a sibling. Line the child's marker up under the first letter of the parent's text.
- What about tabs?
- A tab counts as four spaces, which means one tab at the start of a paragraph makes a code block. Tabs work for nesting lists, but editors disagree about tab width, so spaces are safer in a file other people will edit.
- How do I add a second paragraph inside a list item?
- Leave a blank line, then indent the continuation to line up with the item's text — not its marker. The same rule lets you put a code block, a quote or an image inside an item.