Markdown lists: bulleted, numbered, and nested lists

To make a list in Markdown, start each line with a marker. For an unordered (bulleted) list, begin each line with -, *, or + followed by a space. For an ordered (numbered) list, begin each line with a number, a period, and a space, such as 1.. Indent items to nest sublists, and separate items with blank lines to add spacing. Lists can contain paragraphs, code, and other lists.

Markdown lists syntax reference

Markdown lists key facts

• Unordered list items start with -, *, or + and a space, and all three markers produce the same <ul> output.
• Ordered list items start with a number, a period, and a space, such as 1., and compile to an <ol>.
• Most parsers renumber ordered lists automatically, so only the first number sets the start value.
• Nest a sublist by indenting its items under the parent item, with four spaces being the most portable indentation.
• A tight list has no blank lines between items and renders compactly, while a loose list has blank lines and adds vertical spacing.
• A list item can hold paragraphs, code blocks, and blockquotes when the continuation content is indented under the item.

Choose a list type based on meaning

Use an unordered list when item order does not matter. Use an ordered list for steps, rankings, or any sequence where changing the order changes the meaning. Use a task list when the renderer supports checkboxes and completion state is part of the document.

For nested content, align the child item with the parent item's content column. Four spaces is a safe editorial convention across many renderers, but CommonMark's exact requirement depends on the width of the parent marker. Keep paragraphs, code blocks, and blockquotes indented under the same list item, then preview complex lists before publishing.

Unordered lists

Start each item with -, *, or + and a space. All three markers produce the same result.

Markdown

- First item
- Second item
- Third item

Rendered output

HTML output

<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
</ul>

Pick one marker and use it consistently within a list. Switching markers mid-list can cause some parsers to start a new list.

Ordered lists

Start each item with a number, a period, and a space. The list compiles to an HTML <ol>.

Markdown

1. First item
2. Second item
3. Third item

Rendered output

HTML output

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

The numbers do not have to be correct

Most parsers generate sequential list numbering. In CommonMark, the first marker can set the starting number, while later marker values do not determine each rendered number. Other renderers may apply their own settings.

Markdown

1. First item
1. Second item
1. Third item

Rendered output

Choosing the start number

In CommonMark, GFM, and Pandoc, the first item's number sets where the list starts. Later numbers are ignored, but the first one is honored.

Markdown

5. Starts at five
6. Then six
7. Then seven

Rendered output

HTML output

<ol start="5">
  <li>Starts at five</li>
  <li>Then six</li>
  <li>Then seven</li>
</ol>

Classic Markdown always started ordered lists at 1 regardless of the first number. If you need a specific start value, confirm your renderer honors it.

Nesting lists

Indent an item to nest it under the item above. The required indentation depends on the parent marker and parser. Four spaces is a practical editorial convention, but align nested content with the parent item's content column and preview complex lists.

Markdown

- Fruit
    - Apple
    - Orange
- Vegetables
    - Carrot
    - Pea

Rendered output

HTML output

<ul>
  <li>Fruit
    <ul>
      <li>Apple</li>
      <li>Orange</li>
    </ul>
  </li>
  <li>Vegetables
    <ul>
      <li>Carrot</li>
      <li>Pea</li>
    </ul>
  </li>
</ul>

You can nest ordered and unordered lists inside each other by mixing markers at different levels.

Markdown

1. Prepare
    - Read the brief
    - Gather sources
2. Write
    - Draft
    - Revise

Rendered output

Tight and loose lists

A tight list has no blank lines between items, so the parser omits paragraph tags around each item. A loose list has blank lines between items, so each item's text is wrapped in a <p>, adding vertical spacing. Mixing the two makes the whole list loose.

Markdown (tight)

- One
- Two
- Three

Markdown (loose)

- One

- Two

- Three

Rendered output (loose)

• One

• Two

• Three

The tight version renders compactly; the loose version adds space between items. Choose based on how much breathing room you want.

List items with other elements

A list item can hold more than a single line. Indent continuation content to keep it inside the item.

Item with multiple paragraphs

Markdown

1. First item with a second paragraph.

    This paragraph belongs to the first item because it is indented.

2. Second item.

Rendered output

Item with a code block

Markdown

- Install the package:

    ```bash
    npm install markdific
    ```

- Then import it.

Rendered output

Item with a blockquote

Markdown

- A point worth quoting:

    > Simplicity is the ultimate sophistication.

Rendered output

Flavor differences

Ordered and unordered lists are broadly supported. Differences include ordered-list markers, whether the start number is honoured, and how strictly indentation is parsed. Check the destination renderer for complex nesting.

Two practical notes. First, CommonMark and Pandoc accept ) as an ordered-list marker (1)), while classic Markdown only accepts .. Second, Pandoc's fancy_lists extension supports markers beyond Arabic numerals, such as a., i., and #., which are not portable to other flavors.

Other platforms (Slack, Discord, Notion, Obsidian)

List behavior in chat and note tools varies:

• Slack: supports bulleted and numbered lists in the message composer, but pasted raw Markdown markers may not always convert. Nesting support is limited.
• Discord: supports - and * bullets and 1. numbered lists, including some nesting.
• Notion: converts -, *, and 1. shortcuts into native list blocks as you type, with full nesting.
• Obsidian: full CommonMark list support, including nesting, plus task lists.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders unordered lists as bulleted lists (<ul>) and ordered lists as numbered lists (<ol>), with nested lists indented at each level. A fenced code block placed inside a list item keeps its syntax highlighting.

Try it in the Markdific online editor.

Common mistakes and gotchas

• No space after the marker. -Item or 1.Item will not render as a list. Always put a space after the marker.
• Inconsistent bullet markers. Switching between -, *, and + within one list can split it into separate lists in some parsers. Pick one.
• Under-indented nested items. If a sublist is not indented enough, it flattens into the parent list. Use consistent indentation, and prefer four spaces for portability.
• Missing blank line before the list. Some parsers need a blank line between a paragraph and the first list item, or the list will not start.
• Wrong start number expectations. Only the first number sets the start. Later numbers are ignored. Classic Markdown ignores the start number entirely.
• Accidental loose list. A stray blank line between items turns a tight list loose, adding unexpected spacing. Remove blank lines if you want a compact list.
• Continuation text not indented. A second paragraph in an item must be indented to stay inside the item, or it becomes a separate paragraph after the list.

Best practices

• Use one consistent bullet marker per document. - is the most common and reads cleanly.
• For ordered lists, either number sequentially or write 1. on every line so reordering is painless.
• Indent nested items with four spaces for maximum portability.
• Leave a blank line before and after a list to separate it from surrounding text.
• Keep list items parallel in structure and length so the list scans well.
• Use tight lists for short items and loose lists only when items are long or contain multiple blocks.

HTML equivalent

Unordered lists compile to <ul> with <li> items. Ordered lists compile to <ol> with <li> items, and a custom start becomes the start attribute.

Markdown

- Bulleted

1. Numbered

HTML output

<ul>
  <li>Bulleted</li>
</ul>
<ol>
  <li>Numbered</li>
</ol>

FAQ

How do you create a list in Markdown? For a bulleted list, start each line with -, *, or + and a space. For a numbered list, start each line with a number, a period, and a space, such as 1..

Do the numbers in an ordered list have to be correct? No. Most parsers renumber automatically, so only the first number matters. Writing 1. on every line still produces a correctly numbered list.

How do you start a numbered list at a specific number? Set the first item to that number, for example 5.. In CommonMark, GFM, and Pandoc the list starts there. Classic Markdown ignores the start number and always begins at 1.

How do you nest a list in Markdown? Indent the nested items under the parent item. Four spaces of indentation is the most portable and works across every parser.

What is the difference between a tight and a loose list? A tight list has no blank lines between items and renders compactly. A loose list has blank lines between items, wraps each item in a paragraph, and adds vertical spacing.

Can a list item contain a paragraph or code block? Yes. Indent the continuation content to line up under the item's text, and separate block-level content such as code blocks with a blank line.

Can you mix ordered and unordered lists? Yes. Nest one type inside the other by indenting, for example bullet points under a numbered step.

What HTML does a Markdown list produce? An unordered list produces <ul> with <li> items, and an ordered list produces <ol> with <li> items. A custom start number becomes the start attribute on the <ol>.

How do you make a checklist or to-do list in Markdown? Use a task list, which is a GitHub Flavored Markdown extension. Write each item as - [ ] task for an unchecked box and - [x] task for a checked one. See task lists for where this works.

Can you use letters or roman numerals in a Markdown ordered list? Not in core Markdown, which only accepts Arabic numerals. Pandoc's fancy_lists extension adds letter and roman-numeral markers such as a. and i., but these are not portable to other flavors.

Why does my numbered list restart at 1 in Markdown? A non-list line or an unindented paragraph between items can end the first list and start a second one at 1. Keep the items adjacent, or indent any continuation content so it stays inside the item.

Why is my nested list not indenting in Markdown? The sublist is probably under-indented, so the parser flattens it into the parent list. Indent nested items enough to line up past the parent marker, and prefer four spaces for portability.

Sources and compatibility references

• CommonMark 0.31.2: list items
• CommonMark 0.31.2: lists

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Task lists in Markdown
• Blockquotes in Markdown
• Fenced code blocks
• Paragraphs in Markdown
• Markdown flavors compared