Markdown Lists: Ordered, Unordered, and Nested Syntax

To add a list in Markdown, start each line with a marker: a dash, asterisk, or plus sign for a bulleted list, or a number and a period for a numbered list. Everything that goes wrong afterward, numbering that resets, nesting that collapses, or text that renders as one paragraph, comes down to markers, blank lines, and indentation. This page covers both list families, how a nested Markdown list is built, how to put paragraphs and code under an item without breaking the numbers, and how to fix the three failures people hit most often.

The three list families

Markdown has three list types, and two of them live on this page:

1. An unordered list, the bulleted list built from -, *, or +.
2. An ordered list, the numbered list built from 1., 2., and so on.
3. A task list, where each item starts with - [ ] or - [x].

Task lists combine the unordered syntax with a checkbox and are covered separately in How to Make Checkboxes in Markdown. The rest of this page sticks to plain unordered and ordered syntax.

Unordered lists: the three bullet markers

An unordered Markdown list accepts three interchangeable markers. Each line starts with -, *, or +, a space, then the item text. All three render the same bullet, so these produce identical output:

- First item
- Second item
- Third item

- First item
- Second item
- Third item

Pick one marker and use it for the whole file. Renderers accept any marker, but mixed markers inside one list are harder to maintain, and editors that auto-continue lists will repeat whatever marker the current line uses. A dash is the most common choice because it reads cleanly in raw text and does not collide with emphasis syntax the way an asterisk can.

Ordered lists: what the numbers actually do

An ordered Markdown list starts each line with a number and a period:

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

Two behaviors matter more than the syntax itself:

• The renderer uses the first item's number as the starting value, then renumbers the rest in sequence. A list written as 1., 1., 1. renders as 1, 2, 3, which is why some writers number every item 1. so inserting or deleting a line never forces a renumber. The same behavior makes a list that starts at 3. render starting at 3.
• A blank line between two numbered items does not end the list. As long as the next line is still a list item, the numbering continues. What breaks the list is a non-indented paragraph between items: the list stops, and the next 1. starts a new list at 1.

This is also why a line in normal prose can accidentally become a list item. Text that begins with 1., such as a version number or an enumerated phrase, parses as an ordered list. In the Helix editor discussion on list continuation, a user points out that typing 1. and pressing Enter produces another 1. on the next line, and the renderer still numbers the sequence correctly because every item is renumbered from the first value. If you want a literal 1. at the start of prose text, escape the period as 1\. or rephrase the line.

Nested lists: indentation rules

To nest a list, indent each item of the sublist so it lines up with the content of the parent item. The CommonMark tutorial recommends indenting sublist items by four spaces, and two spaces work for a - parent in most renderers, because two spaces is the width of the - marker plus its space. What matters is that the nested marker starts at or beyond the parent item's content column, not at an arbitrary width.

- Parent item
- Nested item
- Another nested item
- Next parent item

Ordered and unordered lists nest freely inside each other:

1. Setup steps
- Install the app
- Open the project folder
2. Verify the result

Indentation width is the top failure mode, so keep one rule per file and let your editor insert the right spaces. These are the results each indent width produces under a - parent item:

The table is why the safest portable habit is spaces, not tabs. A tab that one renderer reads as four spaces and another reads as eight makes a nested Markdown list render differently on different machines, which defeats the point of a portable text file.

Content under a list item: paragraphs and code without resetting numbers

A list item can hold more than one line: a paragraph, a code block, even a heading. The rule is that every continuation line must be indented to at least the item's content column, and blank lines inside the item must be indented too. A guide on ordered lists with paragraphs demonstrates the pattern: indent each content line by the same number of spaces, blank lines included, and the numbering carries through instead of restarting at 1.

1. Prepare the workspace
   Open the project folder first. This paragraph belongs to item 1
   because it is indented to the content column.
2. Write the list
   ```bash
   # Indented code fences also belong to item 2
   echo "still item 2"

3. Review the rendered output

Three details decide whether this renders correctly:

• The indent applies to the block as a whole, not just its first line. A code fence whose closing fence sits at column zero ends the item.
• Sub-headings can go inside an item, indented the same way, but most writers avoid them because they interrupt list flow in the rendered page.
• If a continuation line is not indented, the item ends. The text renders as a separate paragraph, and the following item continues numbering only if the renderer treats the block as the same list. For line breaks inside a single item, such as wrapping a long item onto two source lines, see Markdown Line Breaks: New Lines, Hard Breaks, and Blank Lines.

Troubleshooting: the three common failures

Everything renders with odd spacing, or items spread into paragraphs. Blank lines between items turn a tight list into a loose one. In a tight list, each item renders as a single line of text. In a loose list, each item wraps in its own paragraph tag, which adds vertical spacing between items and around any nested content. A Hugo Discourse thread on list rendering shows the exact switch: the same source produces <li>text</li> without blank lines and <li><p>text</p></li> with them. Neither is wrong, but if your list suddenly has large gaps, look for a blank line that crept in between items. Numbering resets to 1. Something between two items is not indented far enough, so the list ends and the next 1. starts a fresh list. Check the line directly above the item that restarts: a paragraph, a heading, or a code fence at column zero breaks the chain. Fix it by indenting that line to the content column, or by starting every item with 1. so renumbering never matters. Nesting collapses or shows as plain text. The nested marker is not aligned with the parent item's content column, usually because a tab was used or the indent is one space short. Replace tabs with spaces and indent until the nested marker lines up under the parent's text. If a sublist still renders flat, try the four-space indent, which works in every CommonMark-compatible renderer.

Check list rendering in Fylune with your own files

Syntax guides show examples, but the fastest way to confirm your own list renders the way you intend is to look at the rendered output next to the source. Fylune is a local-first document workspace for Markdown and MDX files that renders rich Markdown, including lists and task lists, inside the document experience, and it works on the ordinary files already in your project folder, offline, with no account required for core editing. Open the file with your list, switch to the rendered view, and compare: do the nested items indent at the depth you wrote, does the numbering survive the paragraph under item 1, and does the list stay tight or loose where you expect? Because the files stay in place, the same document you are checking is the one your other tools and AI agents read, so a fix in Fylune is a fix everywhere. You can try it on your own files at fylune.com/download.

FAQ

How do I add a list in Markdown?

Start each line with a marker. For an unordered list use -, *, or + followed by a space; for an ordered list use 1., 2., 3. followed by a space. Keep items on consecutive lines, and indent nested items to the parent item's content column.

How do I nest a list in Markdown?

Indent each item of the sublist so its marker sits at or beyond the parent item's content column. Two spaces align with a - parent, and four spaces work in every renderer. Use spaces rather than tabs so the nesting renders the same everywhere.

Why did my Markdown list numbering reset?

A non-indented line between items ends the list, so the next 1. starts a new list. Indent any paragraph, code block, or blank line that belongs to an item to the item's content column, or number every item 1. and let the renderer renumber the sequence.

Sources

• Markdown Guide, Basic Syntax: unordered list markers -, *, + and nested list indentation (markdownguide.org)
• CommonMark tutorial, Nested Lists: four-space sublist indent and nesting paragraphs, blockquotes, and code blocks (commonmark.org)
• Bill Agee, Markdown ordered lists with paragraphs: equal indentation of content and blank lines keeps numbering from resetting (blog.likewise.org)
• Hugo Discourse, Rendering of markdown lists depends on content: tight versus loose list rendering (<li> versus <li><p>) (discourse.gohugo.io)
• Helix editor discussion 12812, list continuation behavior and 1.-prefixed items renumbered by the renderer (github.com)
• Julio Merino, Tips on formatting Markdown lists: prefixing every item with 1. (jmmv.dev)
• Stack Overflow, Markdown list number with sub-text under each section: the sub-text-under-item question (stackoverflow.com)
• Keyword demand: DataForSEO keyword_overview, US / en, 2026-10-01 (markdown list 8,100 / KD 26; markdown unordered list 6,600 / KD 11; markdown ordered list 5,400 / KD 1; markdown nested list 1,300 / KD 8)

Structured data for the page (JSON-LD, insert in head)

[
  {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": "Markdown Lists: Ordered, Unordered, and Nested Syntax",
    "url": "https://www.fylune.com/blog/markdown-lists",
    "inLanguage": "en",
    "author": {
      "@type": "Person",
      "name": "Nina@Aurcue",
      "jobTitle": "Chief Marketing Officer at Aurcue",
      "url": "https://www.tiktok.com/@NinaAurcue"
    },
    "publisher": {
      "@type": "Organization",
      "name": "Fylune"
    }
  },
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "How do I add a list in Markdown?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Start each line with a marker. For an unordered list use -, *, or + followed by a space; for an ordered list use 1., 2., 3. followed by a space. Keep items on consecutive lines, and indent nested items to the parent item's content column."
        }
      },
      {
        "@type": "Question",
        "name": "How do I nest a list in Markdown?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Indent each item of the sublist so its marker sits at or beyond the parent item's content column. Two spaces align with a '- ' parent, and four spaces work in every renderer. Use spaces rather than tabs so the nesting renders the same everywhere."
        }
      },
      {
        "@type": "Question",
        "name": "Why did my Markdown list numbering reset?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "A non-indented line between items ends the list, so the next 1. starts a new list. Indent any paragraph, code block, or blank line that belongs to an item to the item's content column, or number every item 1. and let the renderer renumber the sequence."
        }
      }
    ]
  }
]