Markdown Ordered List: Syntax, Numbering, and the Pitfalls That Break It

A Markdown ordered list looks simple (a number, a period, a space, text) until the numbers start doing things you didn't ask for: ignoring the digits you typed, restarting at 1 halfway down the page, or melting into the paragraph above. Most of that behavior is intentional, just undocumented in the one place people actually read: the list itself. This guide covers the real syntax rule, the handful of ways renderers disagree with each other, and why numbering tends to break specifically when Markdown comes from converting another file rather than being typed by hand. If you're dealing with the latter, file2markdown is built to carry list structure through from PDFs, Word docs, and HTML rather than flattening it (more on that workflow below).

The Syntax, and the One Rule That Surprises Everyone

An ordered list item is a number (up to nine digits) followed by a period or a right parenthesis (CommonMark and GFM accept both 1. and 1)), then a space and the item text:

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

The surprising part: in CommonMark and GitHub Flavored Markdown, the actual numbers you type almost never matter. The list starts counting from whatever number the first item uses, and every item after that just increments by one, regardless of what you typed:

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

renders identically to the first example: 1, 2, 3. This isn't a bug. It's useful when you're editing a list and don't want to renumber everything by hand every time you insert a line: write 1. for every item and let the renderer count. It's also why copy-pasting a numbered list from one document into another can silently change its numbers: the renderer was never reading your digits in the first place, only the first one.

To start a list somewhere other than 1, set the first item's number explicitly (5., 6., 7....). Most renderers respect a custom starting number, but not all. If this needs to work everywhere (email clients, older static site generators), test the specific target rather than assuming CommonMark compliance.

Why Your List Restarts at 1 Partway Down

This is a common complaint about ordered lists, and it comes from one thing: a paragraph, image or code block sitting between two items without being indented under the first one. That ends the list. A blank line on its own doesn't; it only makes the list "loose", which wraps each item in a paragraph and usually adds spacing. When the numbers pick back up below it, the renderer has no memory of the previous list: it's a brand-new list that starts at whatever number you typed first, usually 1.

1. Step one
2. Step two

Some explanatory text in between.

1. Step three
2. Step four

renders as two separate lists: (1, 2) and then (1, 2) again, not (1, 2, 3, 4). To keep numbering continuous across an interruption, indent the interrupting content so it lines up with the item's text (three spaces after 1. , four after 10. ), which makes it part of the preceding list item, or explicitly set the next list's starting number (3.) to continue where the first left off. Older renderers that don't follow CommonMark can handle this differently, so if continuous numbering matters (a procedure with a screenshot between steps, for example), check the rendered output rather than assuming it carries over.

Why Your List Merges Into the Paragraph Above

A list can start on the line directly under a paragraph, with no blank line in between, but CommonMark and GFM only allow that when the list starts at 1. Any other start number on the line right after a paragraph is read as more of the paragraph:

The steps are:
3. Open the file
4. Save it

renders as a single run-on paragraph ("The steps are: 3. Open the file 4. Save it"). The same lines starting at 1. render as a paragraph followed by a list. The rule exists so that a hard-wrapped sentence that happens to put a number at the start of a line doesn't turn into a list by accident. The fix is a blank line before the list, which works with any start number.

Nested Lists and Mixing with Bullets

An ordered list can nest another ordered or unordered list inside it, as long as the nested list is indented at least as far as the parent item's text (not just past the marker):

1. Main step
   1. Sub-step a
   2. Sub-step b
2. Next main step
   - A supporting detail (unordered)
   - Another detail

The indentation has to reach where the parent item's text starts (three spaces under 1. ), not just past its number. Indent a sub-list by only two spaces and it falls out of the nesting: numbered sub-steps merge into the parent list as extra top-level steps, and a bullet sub-list splits the ordered list in two. If a nested list looks broken, check the number of leading spaces first; it's almost always an indentation mismatch rather than a syntax error.

Why Numbering Correctness Matters More for AI and RAG Pipelines

A list that restarts at 1 is a minor annoyance for a human reader: you can usually tell from context that "1. Attach the bracket" is really step five. An LLM reading the same Markdown doesn't have that context unless the surrounding prose supplies it, and a chunking pipeline that splits a long procedure into separate chunks (see Chunking Markdown for Vector Databases) can end up with a chunk showing steps "1, 2" that are actually steps "6, 7" of the original, with nothing in that chunk indicating the gap. For Markdown headed into a RAG pipeline or an agent's context window, continuous numbering on multi-step procedures is worth checking by hand.

This is one reason why Markdown works so well for feeding LLMs: plain numbered and bulleted lists carry the same structure as HTML's nested <ol>/<li> tags in far fewer characters, and far more structure than a PDF's visually indented but semantically flat text (the same gap shows up with tables: see Markdown tables vs. HTML tables for RAG).

The Real Workflow: Converting Existing Documents

Numbered lists rarely start life as Markdown: they start as a procedure in a Word document, a PDF manual, or an HTML page, and each represents "number" differently from Markdown's "first number increments, rest don't matter" model. Word and Google Docs store numbering as paragraph metadata, separate from any visible digit. An untagged PDF has no concept of a list at all: "1." is just text at a position on the page, and a converter has to infer list items from indentation and spacing. HTML's <ol>/<li> is unambiguous about list membership but says nothing about why a source document split one sequence into two separate <ol> elements, so a converter that preserves markup faithfully can still emit two Markdown lists that each restart at 1, even when the original read as one sequence.

To see how a given source document converts, try PDF to Markdown, DOCX to Markdown, or HTML to Markdown, then check two things in the result: whether multi-step procedures stayed as one continuous list, and whether nested sub-steps kept their indentation. For more on structure handling across source formats, see the PDF to Markdown guide and the DOCX to Markdown guide.

Frequently Asked Questions

Do the numbers I type in a Markdown ordered list actually matter?

Only the first one. CommonMark and GitHub Flavored Markdown read the first item's number as the starting point, then increment by one for every item after it regardless of what digits you typed. Writing 1. for every item is a common convention specifically because the renderer does the counting for you. The first number also decides whether the list can start directly under a paragraph without a blank line: only a list that starts at 1 can.

Why did my numbered list restart at 1 in the middle of the page?

Something interrupted it: usually a paragraph, image, or code block between two items that isn't indented as part of the preceding list item. (A blank line on its own doesn't end a list.) Markdown treats the interruption as the end of that list, so whatever numbered content follows starts a brand-new list at whatever number you typed first.

How do I nest a list inside an ordered list item?

Indent the nested list so it starts at least where the parent item's text starts (three spaces under 1. ), not just past its number. With too few spaces it falls out of the nesting: numbered sub-steps become extra top-level steps, and a bullet sub-list splits the ordered list in two.

Why did a numbered procedure turn into plain paragraphs after converting a PDF or Word file to Markdown?

An untagged PDF doesn't encode list structure at all, so a converter has to infer it from indentation and spacing, and a conservative converter sometimes declines to guess, leaving a numbered-looking but unlisted paragraph instead. Word and Google Docs store numbering as paragraph metadata that a converter has to translate into a literal Markdown list; if that translation is skipped, the steps come out as plain paragraphs without their numbers. Checking the converted output against the original, rather than assuming any converter infers list structure perfectly, is worth doing for anything beyond a short list.