Markdown Lists: Syntax for Every List Type (2026)

TL;DR: Markdown lists use -, *, or + for unordered (bulleted) items and 1. for ordered (numbered) items. Nest lists by indenting with two to four spaces. The CommonMark specification (version 0.31.2) defines the parsing rules in sections 5.2 and 5.3, and every major platform — GitHub, GitLab, VS Code, Obsidian — follows them. Four-space indentation is the safest choice for nested markdown lists across all renderers.

Markdown lists are one of the most frequently used formatting features in any .md file. Whether you are writing a README, organizing project tasks, or structuring documentation, lists make content scannable and structured. The syntax is simple — a dash or number at the start of a line — but the details around indentation, nesting depth, and platform behavior catch even experienced writers off guard.

This guide covers every list type in Markdown: unordered (bulleted), ordered (numbered), nested, mixed, and task lists. Each section includes the exact syntax, rendered output, and platform-specific gotchas. If you also work with checkboxes inside lists, see the markdown checkbox guide for the full task list syntax. And if line breaks inside list items have been tripping you up, the markdown line break guide explains the four methods that work across renderers.

How Do You Create Unordered Markdown Lists?

Unordered markdown lists (bullet points) start each line with a marker character followed by a space. The CommonMark specification (section 5.2) accepts three marker characters: hyphen (-), asterisk (*), and plus sign (+). All three produce identical HTML output — a <ul> element with <li> children.

- First item
- Second item
- Third item

This renders as:

• First item
• Second item
• Third item

You can also use asterisks or plus signs:

* Asterisk item one
* Asterisk item two
 
+ Plus item one
+ Plus item two

All three markers generate the same <ul> list. The difference is purely a style preference. Hyphens are the most common convention in GitHub repositories — the Google developer documentation style guide recommends hyphens, and most linters (markdownlint rule MD004) default to enforcing a consistent marker across a file.

Consistency rule: Pick one marker and stick with it within a single document. Mixing -, *, and + in the same list is technically valid CommonMark, but most linters flag it, and it makes the source harder to scan. The markdownlint tool enforces consistent markers via rule MD004.

Adding paragraphs inside list items

A list item can contain multiple paragraphs. Separate the paragraphs with a blank line and indent the continuation by the width of the list marker plus one space (typically two or four spaces):

- First item with a longer explanation.
 
  This second paragraph is still part of the first list item
  because it is indented to align with the item text.
 
- Second item starts here.

This produces a single list with two items, where the first item contains two paragraphs. The indentation must align with the content start position of the parent item — not just any indentation will work.

How Do You Create Ordered Markdown Lists?

Ordered markdown lists use a number followed by a period (.) or right parenthesis ()) and a space. The CommonMark specification (section 5.3) defines both as valid ordered list markers, though the period style is far more common.

1. First step
2. Second step
3. Third step

This renders as:

1. First step
2. Second step
3. Third step

Do the numbers matter?

Only the first number matters. CommonMark uses the starting number from the first item and then increments sequentially in the rendered output, regardless of what numbers you write in the source. This means all three of these produce an identical 1, 2, 3 list:

1. Item one
2. Item two
3. Item three

1. Item one
1. Item two
1. Item three

1. Item one
5. Item two
99. Item three

The third example still renders as 1, 2, 3 in HTML — the browser numbers the <ol> sequentially from the first item's start attribute.

Practical tip: Using 1. for every item makes reordering easier. You can move lines around without renumbering. The Markdown Guide recommends sequential numbering for readability, but lazy numbering (all 1.) is valid CommonMark and works on every platform.

For a focused guide on ordered list numbering, starting values, and edge cases across renderers, see the markdown ordered list guide.

Starting from a different number

CommonMark respects the first item's number. If you start with 3., the rendered list begins at 3:

3. Third step
4. Fourth step
5. Fifth step

This outputs an <ol start="3"> in HTML. GitHub, GitLab, VS Code, and Obsidian all honor the start attribute. This is useful for split lists where explanatory text appears between numbered sections.

How Do You Nest Markdown Lists?

Nested markdown lists place a child list inside a parent list item by indenting the child markers. The indentation depth determines the nesting level. This is where most list formatting problems originate — different parsers have different indentation requirements.

The indentation rule

The CommonMark specification requires that a nested list's marker aligns with or falls within the content region of the parent item. For unordered lists with a hyphen marker, this means indenting by at least two spaces:

- Parent item
  - Child item
  - Another child
    - Grandchild item

For ordered lists, the content starts after the number, period, and space — so nesting typically requires three or four spaces:

1. Parent item
   1. Child item
   2. Another child
      1. Grandchild item

Two spaces vs. four spaces

This is the most common source of confusion with markdown lists. The answer depends on your parser:

If you want your markdown lists to render correctly across every platform, use four-space indentation for all nesting. Four spaces works everywhere. Two spaces works on most platforms but breaks on Bitbucket and Pandoc. The Google developer documentation style guide recommends matching the indentation to the content start position, which typically results in two spaces for bullets and four for numbered items.

Safe default: Indent nested items by four spaces. It is the only indentation depth that works across every CommonMark-compatible parser, including strict implementations like Bitbucket and Pandoc. You sacrifice some visual compactness in the source, but you gain universal compatibility.

Mixing ordered and unordered lists

You can nest an ordered list inside an unordered list, or vice versa. The parser treats each nesting level independently:

- Shopping categories
    1. Produce
    2. Dairy
    3. Bakery
- Errands
    1. Post office
    2. Dry cleaner

And the reverse:

1. Project setup
    - Install dependencies
    - Configure environment
    - Run initial build
2. Development
    - Write feature code
    - Add unit tests

Both patterns are valid CommonMark. The key is consistent indentation — all child items at the same nesting level must be indented the same number of spaces. You can also use inline formatting like strikethrough or bold inside any list item, regardless of nesting depth.

What Are the Most Common Markdown List Mistakes?

Five syntax errors cause nearly all broken list rendering. Each one fails silently — no error message, just unexpected output. Knowing these patterns saves debugging time.

Mistake 1: Missing blank line before a list

Some parsers require a blank line between a paragraph and the first list item. Without it, the list may render as plain text:

Here is my list:
- Item one
- Item two

Add a blank line to guarantee correct rendering:

Here is my list:
 
- Item one
- Item two

CommonMark does not strictly require the blank line, but GitHub's Markdown renderer and several other parsers handle it more reliably with one. Adding a blank line before every list is a safe habit.

Mistake 2: Inconsistent indentation in nested lists

Mixing two-space and four-space indentation within the same nested structure confuses parsers:

- Parent
  - Child (2 spaces)
      - Grandchild (6 spaces — inconsistent)

Fix: pick one indentation width and apply it uniformly at each nesting level.

Mistake 3: Missing space after the list marker

The space between the marker and the text is mandatory. Without it, the line is not parsed as a list item:

-No space — renders as plain text
- Space present — renders as a list item

Mistake 4: Broken continuation in multi-line items

When a list item spans multiple lines (with paragraphs, code blocks, or additional content), the continuation lines must be indented to align with the item's content start:

1. First item with a code block:
 
   ```bash
   echo "This is indented correctly"

2. Second item continues the list.

If the code block is not indented by at least three spaces (aligning with the `F` in `First`), the list breaks and the code block renders outside the list structure.

### Mistake 5: Using a tab instead of spaces

Tabs and spaces are not interchangeable in list indentation. The CommonMark specification treats a tab as advancing to the next tab stop (multiples of four), which can produce unexpected nesting depths. Spaces give you predictable control. Configure your editor to insert spaces when you press Tab inside Markdown files.

I tested the same nested list across six renderers while building [MacMD Viewer](https://macmdviewer.com/features) and found that tab-indented lists rendered differently on four of them. Switching to four spaces resolved every inconsistency. If you are converting documentation from another format, the [HTML to Markdown converter](/tools/html-to-markdown) preserves list nesting with space-based indentation by default.

## Which Platforms Support Markdown Lists?

Every platform that supports Markdown renders basic unordered and ordered lists. The differences appear in nesting behavior, continuation content, and advanced features like task lists.

| Platform | Basic lists | Nested lists | Task lists | Loose/tight distinction |
|----------|------------|-------------|------------|------------------------|
| GitHub (GFM) | Yes | 2+ spaces | Yes | Yes |
| GitLab (GLFM) | Yes | 2+ spaces | Yes | Yes |
| VS Code preview | Yes | 2+ spaces | Yes | Yes |
| Obsidian | Yes | 2+ spaces | Yes | Partial |
| Bitbucket | Yes | 4 spaces | No | Yes |
| Pandoc | Yes | 4 spaces | Yes (ext) | Yes |
| Reddit | Yes | 4 spaces | No | No |
| CommonMark (strict) | Yes | Content-aligned | No | Yes |

The "loose/tight distinction" column refers to whether the parser adds `<p>` tags inside list items when blank lines separate them (loose list) versus omitting `<p>` tags when items have no blank lines between them (tight list). This affects vertical spacing in the rendered output.

If you write markdown files on macOS and want to preview how your lists render before pushing to GitHub, [MacMD Viewer](https://macmdviewer.com/download) uses a GFM-compatible renderer that handles all list types — including nested lists, mixed ordered/unordered, and task lists. It renders the file instantly as you edit in your preferred text editor, so you catch indentation issues before they reach your repository.

You can also convert your Markdown to HTML with the free [Markdown to HTML converter](/tools/markdown-to-html) to inspect the exact `<ul>`, `<ol>`, and `<li>` structure your lists produce.

## How Do You Add Content Inside List Items?

Markdown lists can contain more than just text. The [CommonMark specification](https://spec.commonmark.org/) allows any block-level content inside a list item — paragraphs, code blocks, blockquotes, images, and even other lists — as long as the content is indented correctly.

### Code blocks inside list items

Indent a fenced code block to align with the list item content:

```markdown
1. Install the package:

   ```bash
   npm install markdown-it

2. Import it in your code:

   import markdownit from 'markdown-it'

The triple backticks must be indented by the same amount as the item text (three spaces for a `1.` marker).

### Blockquotes inside list items

Indent the blockquote marker (`>`) to match the item content:

```markdown
- Key finding:

  > Lists are the third most used Markdown feature after headings
  > and paragraphs, based on analysis of 10,000 GitHub README files.

- Another point follows.

Images inside list items

Images follow the same indentation rule:

1. Screenshot of the dashboard:
 
   ![Dashboard view](./images/dashboard.png)
 
2. Click the settings icon in the top right.

The blank line before the image and the correct indentation keep the image attached to the list item rather than breaking the list.

How Do Markdown Lists Convert to HTML?

Understanding the HTML output helps debug rendering issues. The CommonMark specification (section 5) defines how each list marker maps to HTML elements: -, *, + produce <ul>, and 1. produces <ol>. Here is the exact mapping.

Unordered list:

- Apple
- Banana
- Cherry

Produces:

<ul>
  <li>Apple</li>
  <li>Banana</li>
  <li>Cherry</li>
</ul>

Ordered list:

1. First
2. Second
3. Third

Produces:

<ol>
  <li>First</li>
  <li>Second</li>
  <li>Third</li>
</ol>

Nested list:

- Fruits
    - Apple
    - Banana
- Vegetables
    - Carrot
    - Spinach

Produces:

<ul>
  <li>Fruits
    <ul>
      <li>Apple</li>
      <li>Banana</li>
    </ul>
  </li>
  <li>Vegetables
    <ul>
      <li>Carrot</li>
      <li>Spinach</li>
    </ul>
  </li>
</ul>

If you need to inspect the exact HTML output of your markdown lists, the Markdown to HTML converter on this site shows the rendered HTML side by side with your Markdown source.

How Do You Preview Markdown Lists on macOS?

macOS does not include a built-in Markdown renderer. Quick Look shows .md files as plain text by default, which means you cannot verify list indentation or nesting without a third-party tool.

MacMD Viewer — A native macOS app that renders Markdown with full GFM support, including all list types, nested structures, syntax highlighting, and Mermaid diagrams. It registers as the default .md file handler, so double-clicking any Markdown file opens a rendered preview instantly. The GFM-compatible parser handles two-space and four-space indentation identically to GitHub. Download MacMD Viewer ($19.99, one-time purchase).

VS Code — Open a .md file and press Cmd+Shift+V for the built-in preview. The renderer handles all standard list types and nesting, though task list checkboxes are not interactive.

Terminal with Glow — Install Glow via Homebrew (brew install glow) and run glow file.md for a terminal-rendered preview with list formatting.

Frequently Asked Questions

How do you make a bullet list in Markdown?

Type a hyphen (-), asterisk (*), or plus sign (+) followed by a space and your text. Each item goes on its own line. Hyphens are the most common convention — the Google developer documentation style guide recommends them, and most linting tools default to hyphens. All three markers produce identical <ul> HTML output.

How do you create a numbered list in Markdown?

Start each line with a number, a period, and a space: 1. First item. The CommonMark specification (section 5.3) only uses the first item's number to set the starting value — subsequent items are numbered automatically regardless of what numbers you type in the source.

How many spaces do you need to nest a Markdown list?

Two spaces work on GitHub, GitLab, VS Code, and Obsidian for unordered lists. Four spaces are required on Bitbucket, Pandoc, and Reddit. For maximum compatibility across all platforms, use four-space indentation. The CommonMark specification requires alignment with the parent item's content start position.

Can you mix ordered and unordered lists in Markdown?

Yes. Nest an ordered list inside an unordered list (or the reverse) by indenting the child list. Each nesting level is parsed independently — the parent list type does not affect the child. Consistent indentation is the only requirement.

Why is my Markdown list not rendering correctly?

The five most common causes are: missing blank line before the list, inconsistent indentation in nested items, missing space after the list marker, incorrect continuation indentation for multi-line items, and tabs instead of spaces. Check each of these in order. You can also paste your Markdown into our free Markdown to HTML converter to see the exact HTML structure your syntax produces.