The Number You Type in a Markdown List Is Only a Suggestion

In CommonMark — the Markdown specification that GitHub and many other renderers implement — only the first number of an ordered list reaches the page. The browser counts the rest. Only a numbered list that starts at 1. can begin directly under a line of text. So the digits in your raw file and the numbers on screen can disagree.

Take one line:

1986. What a great season.

John Gruber's own Markdown.pl — version 1.0.1, dated 14 December 2004 — turns it into a one-item list, and the year is gone:¹

<ol>
<li>What a great season.</li>
</ol>

The reader sees "1. What a great season." Today's CommonMark spec, version 0.31.2, keeps the year but still builds a list — an <ol start="1986"> that the browser indents and numbers for you:²

<ol start="1986">
<li>What a great season.</li>
</ol>

Twenty years apart, the same file renders two ways. Neither is the sentence you wrote.

The confusion is durable. Stack Overflow's "Markdown: continue numbered list", asked in 2013, had 417,685 views and a score of 826 as of 26 October 2026.³ This reference covers the numbering rules every CommonMark renderer agrees on: the start number, which lines may open a list, the marker itself, and continuation. Then come the two ways to number lists in notes you read raw, and a lint rule to hold you to one.

The basics live in the complete Markdown cheat sheet; nesting has its own precise rule.

Only the first number reaches the page

CommonMark reads the number on a list's first item as its start and ignores every number after it. Type 3., 4., 9. and the page shows 3, 4, 5. HTML could carry each item's own number, but none of the four renderers tested here does. Your later digits live only in the raw file.

The spec says it in two sentences: "The start number of an ordered list is determined by the list number of its initial list item. The numbers of subsequent list items are disregarded."²

3. three
4. four
9. nine

<ol start="3">
<li>three</li>
<li>four</li>
<li>nine</li>
</ol>

The 9 is not in the output at all. The browser draws 3, 4 and 5 from one start attribute.

That is a change from where Markdown began. Gruber's 2004 syntax page put it more strongly: "the actual numbers you use to mark the list have no effect on the HTML output Markdown produces."⁴ In his Markdown.pl even the first number was thrown away — the same three lines render as 1, 2, 3.

The page also made a promise: "At some point in the future, Markdown may support starting ordered lists at an arbitrary number."⁴ CommonMark kept it — for the first item only.

Lazy numbering works for the same reason. Every item says 1., and the browser counts:

1. one
1. two
1. three

That renders as 1, 2, 3 in both Markdown.pl and CommonMark.

Nothing in HTML forces the renderer to drop your numbers. The HTML Standard gives <ol> a start attribute — it "is used to determine the starting value of the list" — and gives each <li> a value attribute, which "is used to determine the ordinal value of the list item, when the li's list owner is an ol element."⁵ Across sixteen test inputs and four renderers — 64 outputs — not one emits value.

The renderer drops your numbers by design, not by necessity.

Why 1986. becomes a list and 2. after a sentence doesn't

A numbered line can open a list in two places: at the start of a block, which is the top of the file or just after a blank line, or directly under a line of text. Any number works at a block start. Directly under text, CommonMark accepts only 1.. So a year that opens a paragraph becomes a list.

Two shopping notes show the rule. The first stays one paragraph:

Shopping:
2. eggs
3. milk

<p>Shopping:
2. eggs
3. milk</p>

Change one digit and you get a paragraph followed by a list:

Shopping:
1. eggs
2. milk

<p>Shopping:</p>
<ol>
<li>eggs</li>
<li>milk</li>
</ol>

The spec gives the reason plainly: "In order to solve the problem of unwanted lists in paragraphs with hard-wrapped numerals, we allow only lists starting with 1 to interrupt paragraphs."⁶ Hard-wrapped prose often puts a number at the start of a line — a page count, a total, a year. Without the rule, every such line would split its paragraph.

The same logic explains the year. Directly under a sentence, 1986. is not 1., so it stays inside the paragraph:

It was a long season.
1986. A great year.

<p>It was a long season.
1986. A great year.</p>

Put a blank line above it, or make it the first line of the file, and nothing is being interrupted. Any number may start a list there — and 1986. does.

The rule is a compromise, and its author says so. The spec admits it still misfires when the wrapped number happens to be 1:

The number of windows in my house is
1.  The number of doors is 6.

"We may still get an unintended result in cases like" that one, the spec concedes, "but this rule should prevent most spurious list captures."⁶ John MacFarlane, who wrote the spec, called it "an ugly heuristic (we only allow an ordered list to interrupt a paragraph when the list number is 1)" in an April 2018 essay.⁷

His later markup language, Djot, drops the exception entirely: "Paragraphs can never be interrupted by other block-level elements, and must always end with a blank line (or the end of the document or containing element)."⁸

The fix for a line-opening year goes back to Gruber. His syntax page names the trap — "It’s worth noting that it’s possible to trigger an ordered list by accident" — and the cure: "To avoid this, you can backslash-escape the period".⁴

1986\. What a great season.

<p>1986. What a great season.</p>

The backslash vanishes from the output. The question it answers — "In Markdown, how do I start a line with a number without creating a list?" — had 16,223 views on Stack Overflow as of 26 October 2026.⁹

What counts as a list number: digits, a delimiter, nine places

An ordered-list marker in CommonMark is one to nine digits followed by a period or a closing parenthesis. Ten digits is plain text. Zero is a valid start, leading zeros are dropped, and a negative number is not a list. Switching from . to ) partway through quietly starts a second list.

The spec's definition carries its own aside on the limit: "An ordered list marker is a sequence of 1–9 arabic digits (0-9), followed by either a . character or a ) character. (The reason for the length limit is that with 10 digits we start seeing integer overflows in some browsers.)"¹⁰

123456789. ok

<ol start="123456789">
<li>ok</li>
</ol>

1234567890. not ok

<p>1234567890. not ok</p>

The spec's own examples cover the rest — 0. gives start="0", 003. gives start="3", and -1. stays a paragraph.¹⁰

The delimiter is part of a list's identity. The spec is blunt: "Changing the bullet or ordered list delimiter starts a new list".¹¹

1. one
2) two

<ol>
<li>one</li>
</ol>
<ol start="2">
<li>two</li>
</ol>

On screen that can pass for one list with an odd gap above item 2. In the HTML it is two lists, and anything that reads the HTML — a stylesheet, a converter, assistive software — sees two.

Letters and Roman numerals are not list markers in CommonMark at all; the definition says digits. Pandoc, MacFarlane's document converter, adds them through its fancy_lists extension: "Unlike original Markdown, pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to Arabic numerals."¹² Even there, a capital letter followed by a period needs two spaces after it. The manual's reason is a good one:

The point of this rule is to ensure that normal paragraphs starting with people’s initials, like B. Russell won a Nobel Prize (but not for "On Denoting"). do not get treated as list items.¹²

Continuing a numbered list after a paragraph or code block

Anything unindented between two items ends the list. Whether the next part keeps counting depends on what you typed. A real number such as 3. becomes the new list's start, so the count carries on. A lazy 1. starts over at 1. Indenting the interruption under the item keeps one list instead.

This is the most-asked numbering question of all. "Markdown: continue numbered list" has 17 answers and 417,685 views.³ The receipts below are the whole answer.

With real numbers, the count survives a paragraph:

1. one
2. two

A note between.

3. three

<ol>
<li>one</li>
<li>two</li>
</ol>
<p>A note between.</p>
<ol start="3">
<li>three</li>
</ol>

With lazy numbers it does not. The same input with 1. three renders a second list that begins again at 1.

A code block has the same effect when it sits at the left margin:

1. one

```
code
```

2. two

That produces a list, then the code, then a fresh <ol start="2">. The count survives only because the 2. was typed. Indent the fence three spaces — the width of 1. — and the code belongs to item 1, so there is only one list:

1. one

   ```
   code
   ```

2. two

<ol>
<li>
<p>one</p>
<pre><code>code
</code></pre>
</li>
<li>
<p>two</p>
</li>
</ol>

Indenting a paragraph works the same way. The cost is visible: the list becomes "loose", so each item is wrapped in <p> and gets paragraph spacing.

Three spaces is not arbitrary. Content under a list item lines up with the text after its marker — which is also why a nested list under 1. needs three spaces, not two. That rule, and how to test it across parsers, is covered in the Markdown edge cases that break editors.

Lazy numbering or real numbers: what each costs

Lazy numbering — 1. on every line — survives reordering and keeps diffs small, and Google's Markdown style guide recommends it for long lists that change. Real numbers read correctly in the raw file and carry a count across interruptions. The same guide prefers them for short, stable lists.

Google's guide states both halves. The first:

For longer lists that may change, especially long nested lists, use "lazy" numbering:¹³

And the second, a few lines later:

However, if the list is small and you don't anticipate changing it, prefer fully numbered lists, because it's nicer to read in source:¹³

The term itself is older. Gruber's 2004 page already said, "If you do use lazy list numbering, however, you should still start the list with the number 1."⁴

The trade-off, measured against the cases in this piece:

For notes you keep as plain files, the deciding question is who reads the raw text. If it is you — in a text editor, a terminal, a diff — real numbers tell the truth there too. If lists are long and reordered often, lazy numbers save the renumbering, and the raw file stops telling you the order.

A short house rule to paste into a notes folder's README:

List numbering in this folder
- Short, stable lists: real numbers (1. 2. 3.).
- Long lists that get reordered: lazy numbers (1. 1. 1.).
- Never change . to ) inside one list.
- A paragraph that opens with a year: escape it (1986\.).
- Code or notes inside a list: indent them under the item.
- Lint with markdownlint MD029.

Enforce one rule with markdownlint MD029

markdownlint's rule MD029, also called ol-prefix, checks list numbers in one of four styles: one, ordered, zero, or the default one_or_ordered, which accepts either of the first two. Choose one for lazy lists or ordered for real numbers. One catch: every style flags a list that resumes at 3..

The rule's documentation describes its trigger: "This rule is triggered for ordered lists that do not either start with '1.' or do not have a prefix that increases in numerical order (depending on the configured style)."¹⁴ A .markdownlint.json that pins real numbers:

{
  "MD029": { "style": "ordered" }
}

The catch appears when the rule meets the continuation technique above. markdownlint treats the resumed 3. as a new list that should start at 1. A run of markdownlint 0.42.0 on 26 October 2026, on the 1. 2. — paragraph — 3. input, flagged these items:

style            items flagged
one_or_ordered   3.        (Expected: 1; Actual: 3)
one              2. 3.
ordered          3.        (Expected: 1; Actual: 3)
zero             1. 2. 3.

No style accepts a list that legitimately starts at 3. There are two ways through. Indent the note under item 2, so there is only one list — that passes under ordered and one_or_ordered. Or switch the rule off around the resumed list:

1. one
2. two

A note between.

<!-- markdownlint-disable MD029 -->
3. three
4. four
<!-- markdownlint-enable MD029 -->

That passed under ordered and one_or_ordered, and still rendered as <ol start="3">. The comments do not appear in the rendered text. A single disable-next-line comment is not enough; in the same test it silenced item 3 and still flagged item 4.

The documentation names the code-block version of the same problem:

Note: This rule will report violations for cases like the following where an improperly-indented code block (or similar) appears between two list items and "breaks" the list in two:¹⁴

Its fix is the one from the previous section — indent the block.

markdownlint checks more than lists. Where each tool reads a note's title covers its two title rules.

Sixteen cases to test your own renderer

These rules are the spec, not one tool's quirk. On 26 October 2026, sixteen inputs went through three CommonMark implementations — markdown-it-py 3.0.0, commonmark.js 0.31.2 and GitHub's Markdown API — and produced identical HTML in all sixteen. Gruber's Markdown.pl 1.0.1 differed in eleven. Run them through yours.

⏎ marks a line break; a blank line is ⏎⏎.

CommonMark emits a start attribute in seven of the sixteen outputs; Markdown.pl emits it in none. Of Markdown.pl's eleven differences, nine are numbering rules, and two exist only because it predates fenced code blocks.

Two limits. A renderer that does not follow CommonMark may disagree with any row — Markdown.pl is the proof. And some editors renumber lists while you type; that is an editing feature, separate from rendering, and nothing here tests it.

Frequently asked questions

The questions below are the ones people actually type, several of them Stack Overflow titles viewed thousands to hundreds of thousands of times. Each answer applies to CommonMark renderers and was checked against the sixteen cases above; a renderer that does not follow CommonMark may differ.

How do I continue a numbered list in Markdown?

Type the real number when you resume. After an unindented paragraph, 3. starts a new list at 3; a lazy 1. restarts at 1. To keep a single list, indent the paragraph or code block under the previous item by the marker's width — three spaces under 1. . markdownlint MD029 flags a resumed 3. under every style.

How do I create an automatically numbered list in Markdown?

Write 1. at the start of every item. CommonMark uses only the first item's number as the list's start, and the browser counts the rest, so 1. 1. 1. renders as 1, 2, 3. Google's Markdown style guide calls this lazy numbering and recommends it for long lists that change. Short, stable lists read better with real numbers.

In Markdown, how do I start a line with a number without creating a list?

Put a backslash before the period: 1986\. What a great season. renders as plain text, with no backslash. The escape is only needed when the line opens a paragraph — at the top of the file or after a blank line. Directly under a line of text, any number except 1 stays in the paragraph anyway.

How to prevent/disable automatic list number incrementing in markdown?

In CommonMark output you cannot keep a different number on each item. The renderer emits one start attribute for the first number and lets the browser count from there. HTML's value attribute on <li> could hold each number, but none of the four renderers tested emits it. To keep a numbered line as plain text, escape its period.

How do you make lettered lists using markdown?

CommonMark has no lettered lists — a list marker must be one to nine digits. Pandoc's fancy_lists extension adds letters and Roman numerals. A capital letter with a period then needs two spaces after it, so initials like "B. Russell" are not mistaken for list items. Stack Overflow's version of this question had 221,436 views on 26 October 2026.

Why does a code block break my numbered list in Markdown?

A fenced code block at the left margin ends the list. The next item starts a new list — at its typed number if real, at 1 if lazy. Indent the fence to line up with the item's text, three spaces under 1. , and the code becomes part of that item. markdownlint's MD029 documentation names this exact case.

Should I number Markdown lists 1. 1. 1. or 1. 2. 3.?

Both render correctly. Use 1. 2. 3. when you read the raw file or the list is short and stable; Google's style guide says that is "nicer to read in source". Use 1. 1. 1. for long lists you reorder often. Then pin the choice with markdownlint MD029, set to ordered or to one.

The renderer keeps one number. The file keeps all of them — so type the ones you want a reader of the file to see.

MNMNOTE keeps notes as open Markdown on your own device, where the raw file is the note: mnmnote.com.