Markdown Ordered List: Complete Syntax Guide (CommonMark 0.31.2)

TL;DR: Markdown ordered lists use a number, a period, and a space — 1. Item. Only the first number affects the rendered output; the CommonMark spec (section 5.3) auto-increments all subsequent items. Lazy numbering (1. 1. 1.) is fully valid and makes reordering painless. Use four-space indentation to nest ordered lists safely across GitHub, GitLab, Pandoc, and Bitbucket.

Ordered lists are one of the most useful formatting tools in Markdown. Step-by-step instructions, ranked recommendations, structured outlines — all of them benefit from numbered items that carry inherent sequence. The syntax looks trivial at first glance, but there are enough edge cases around numbering behavior, nesting indentation, and cross-platform compatibility to trip up even experienced Markdown writers.

This guide covers everything about ordered list syntax in Markdown: the basic form, lazy numbering, custom start values, nesting rules, HTML output, and the common mistakes that cause silent rendering failures. For a broader look at all list types — including unordered and task lists — see the markdown lists guide. If nesting multiple levels is your primary concern, the markdown nested lists guide goes deeper on indentation strategies and parser differences.

What Is the Basic Syntax for a Markdown Ordered List?

An ordered list in Markdown starts each item with a number, a period, and a space. The CommonMark specification (section 5.3) defines the ordered list marker as one to nine digits followed by either a period (.) or a right parenthesis ()). The period style is the universal standard — use it for all platforms.

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

This renders as an HTML <ol> element with three <li> children:

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

The browser then renders that as a sequentially numbered list with the default counter styling. The visual output is the familiar 1., 2., 3. you expect.

Every major Markdown platform — GitHub, GitLab, VS Code, Obsidian, Pandoc, Reddit — supports this basic syntax. The differences only emerge with nesting depth, continuation content, and the period-versus-parenthesis marker choice.

Do the Numbers in a Markdown Ordered List Actually Matter?

Only the first number matters. This is one of the most misunderstood behaviors in Markdown, and the CommonMark spec is explicit about it: the parser reads the first item's number to set the start attribute on the <ol> element, then ignores every subsequent number and increments sequentially in the HTML output.

All three of the following produce an identical rendered list numbered 1, 2, 3:

Sequential numbering (most readable source):

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

Lazy numbering (easiest to maintain):

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

Out-of-order numbering (still renders 1, 2, 3):

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

All three produce <ol start="1"> with three <li> elements. The browser counter handles the visual numbering — your source numbers after the first item are irrelevant.

Practical advantage of lazy numbering: If you write 1. on every line, you can reorder items by cut-and-paste without ever renumbering. This is why many style guides — including the Markdown Guide — recommend lazy numbering for lists that are frequently edited. The rendered output is identical, and the source stays clean through refactoring.

How Do You Start a Markdown Ordered List from a Number Other Than 1?

Set the first item to your desired starting number. CommonMark uses that value for the <ol start> attribute, and the browser renders from there.

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

This outputs:

<ol start="3">
  <li>Third step</li>
  <li>Fourth step</li>
  <li>Fifth step</li>
</ol>

The browser renders 3., 4., 5. — exactly what you wrote. This is useful for split lists where you insert explanatory paragraphs or diagrams between numbered sections. You can pick up numbering exactly where you left off.

GitHub, GitLab, VS Code, Obsidian, and Pandoc all honor the start attribute. Reddit does not — it always resets to 1 regardless of the first number. If Reddit is a target platform, avoid relying on custom start values.

Can You Use Parentheses Instead of a Period in Ordered Lists?

The CommonMark specification allows both 1. and 1) as valid ordered list markers. In practice, parenthesis-style lists have significant compatibility problems:

1) First item
2) Second item
3) Third item

The parenthesis style is only safe if your target is a strict CommonMark renderer or Pandoc. For everything else — GitHub READMEs, GitLab wikis, VS Code previews, Obsidian notes — use the period. Stick with 1. as the universal default.

How Do You Nest Ordered Lists in Markdown?

Nested ordered lists place a child list inside a parent item by indenting the child markers. The key question is how many spaces to use — and the answer depends on the marker width.

The CommonMark indentation rule

The CommonMark specification requires that nested content aligns with the content start position of the parent item. For a single-digit ordered list marker (1.), the content starts at position 3 (the digit, the period, the space = three characters). So nested items need at least three spaces of indentation:

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

For a two-digit marker (10.), the content starts at position 4, requiring four spaces for nesting.

Cross-platform nesting compatibility

Different renderers interpret indentation differently. Here is what works on each major platform:

Safe universal default: four spaces. Four-space indentation renders correctly on every platform in the table. Using three spaces breaks on GitLab, Bitbucket, Pandoc, and Reddit. Using two spaces breaks on even more. The markdown nested lists guide covers this indentation matrix in full detail for all nesting depths.

1. First level item
    1. Second level item
    2. Another second level
        1. Third level item
        2. Another third level
2. Back to first level

How Do You Mix Ordered and Unordered Lists?

You can nest an ordered list inside an unordered list and vice versa. Each nesting level is parsed independently — the parent list type does not constrain the child.

Ordered inside unordered:

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

Unordered inside ordered:

1. Project setup
    - Install dependencies
    - Configure environment variables
    - Run the initial build
2. Development
    - Write feature code
    - Add tests
3. Deployment
    - Build for production
    - Push to server

This pattern is extremely common in technical documentation and READMEs — a numbered procedure where each step has a bullet-point checklist of sub-tasks. The CommonMark specification treats each nesting level as a new list context. For more examples and cross-platform behavior of mixed lists, see the markdown lists guide.

How Do Markdown Ordered Lists Convert to HTML?

Understanding the HTML output lets you predict rendering behavior and debug issues. Every ordered list in Markdown maps directly to <ol> and <li> elements.

Basic ordered list:

1. First
2. Second
3. Third

HTML output:

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

Custom start value:

5. Fifth
6. Sixth
7. Seventh

HTML output:

<ol start="5">
  <li>Fifth</li>
  <li>Sixth</li>
  <li>Seventh</li>
</ol>

Nested ordered list:

1. Parent
    1. Child A
    2. Child B
2. Next parent

HTML output:

<ol>
  <li>Parent
    <ol>
      <li>Child A</li>
      <li>Child B</li>
    </ol>
  </li>
  <li>Next parent</li>
</ol>

Each nesting level gets its own <ol> element. Browser default styling restarts the counter at 1 for nested lists and uses a different list-style-type (typically lower-alpha or lower-roman for deeper levels, depending on the browser's user-agent stylesheet).

You can inspect the exact HTML your ordered list syntax produces using the free Markdown to HTML converter — useful when debugging nesting or start attribute behavior.

What Are the Most Common Ordered List Mistakes?

Four errors account for nearly all broken ordered list rendering. None produce error messages — the list either renders incorrectly or not at all.

Mistake 1: Wrong indentation depth when nesting

Using two spaces instead of three (or four) for nested ordered list items is the most common mistake. It works on VS Code and Obsidian, fails silently on GitHub when nesting deeper than one level, and breaks entirely on Pandoc and Bitbucket:

1. Parent item
  1. Child — only 2 spaces, will break on strict parsers

Fix: Use four spaces for all nested ordered list content:

1. Parent item
    1. Child — four spaces, works everywhere

Mistake 2: Missing space after the period

The space between the period and the item text is not optional. Without it, the line is parsed as plain text:

1.No space — renders as paragraph text "1.No space"
1. Space present — renders as a list item

Mistake 3: Not adding a blank line before the list

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

Here are the steps:
1. First step
2. Second step

Safer version:

Here are the steps:
 
1. First step
2. Second step

CommonMark does not strictly require the blank line, but GitHub's parser and several others handle it more reliably with one. Adding a blank line before every list is a low-cost habit with high payoff.

Mistake 4: Incorrect continuation indentation

When a list item spans multiple paragraphs or contains a code block, the continuation content must be indented to align with the item text. For a 1. marker (three characters wide), that means three spaces:

1. First item with explanation.
 
   This continuation paragraph is part of the first item.
   Three spaces align it with the "F" in "First".
 
2. Second item.

A code block inside a list item follows the same rule:

1. Install the package:
 
   ```bash
   npm install remark

2. Continue with the next step.

If the code block is not indented to align with the item text, it breaks out of the list structure and renders as a top-level fenced code block after a broken list.

## Which Platforms Support Markdown Ordered Lists?

Every Markdown-capable platform supports basic ordered lists. The variations appear in nesting behavior, the `start` attribute, and the parenthesis-style marker.

| Platform | Basic ordered list | Custom start | Parenthesis (1)) | Min nest indent |
|----------|-------------------|--------------|------------------|-----------------|
| GitHub (GFM) | Yes | Yes | No | 3 spaces |
| GitLab (GLFM) | Yes | Yes | No | 4 spaces |
| VS Code preview | Yes | Yes | No | 2 spaces |
| Obsidian | Yes | Yes | No | 2 spaces |
| Bitbucket | Yes | Yes | No | 4 spaces |
| Pandoc | Yes | Yes | Yes | 4 spaces |
| Reddit | Yes | No (resets to 1) | No | 4 spaces |
| CommonMark (strict) | Yes | Yes | Yes | Content-aligned |

The most significant practical limitation is Reddit's behavior — it resets all ordered lists to start at 1 regardless of the source, which means split numbered lists do not work there.

## How Do You Add Content Inside Ordered List Items?

The CommonMark specification allows any block-level content inside a list item: additional paragraphs, code blocks, blockquotes, images, or nested lists. All of it must be indented to align with the item's content start position.

**Multiple paragraphs:**

```markdown
1. First step with more to say.

   This is a second paragraph inside the first item. It is
   indented three spaces to align with the item text.

2. Second step.

Blockquote inside an item:

1. Key finding from the research:
 
   > Ordered lists are used in 67% of technical documentation
   > files on GitHub, according to the 2024 analysis.
 
2. Implication for documentation standards.

Image inside an item:

1. Open the settings panel:
 
   ![Settings panel screenshot](./images/settings.png)
 
2. Click the "Advanced" tab.

The blank line before the continuation content and the correct indentation are both required. The blank line signals a loose list item (which wraps text in <p> tags), and the indentation keeps the content associated with the correct item rather than breaking the list. For more on loose versus tight list behavior, see the markdown lists guide.

How Do You Preview Markdown Ordered Lists on macOS?

macOS does not render Markdown files natively — Quick Look shows .md files as raw text by default, which means you cannot verify ordered list numbering, nesting, or HTML output without a separate tool.

MacMD Viewer renders Markdown files with a GFM-compatible parser that handles all ordered list features: basic numbering, lazy numbering, custom start values, nested lists, and continuation content. It opens any .md file instantly via double-click or Quick Look, so you can catch indentation mistakes and nesting issues before they reach GitHub or your documentation system. Download MacMD Viewer ($19.99, one-time purchase — no subscription).

VS Code — Open a .md file and press Cmd+Shift+V for the built-in Markdown preview. It handles all standard ordered list syntax and honors custom start values.

Pandoc (terminal) — Convert your file to HTML and open it in a browser: pandoc file.md -o file.html && open file.html. Pandoc uses a strict CommonMark parser and supports both period and parenthesis markers, making it useful for validating cross-platform behavior.

You can also paste any ordered list into the free Markdown to HTML converter to inspect the exact <ol>, <li>, and start attribute structure your syntax produces.

Frequently Asked Questions

How do you write an ordered list in Markdown?

Type a number, a period, and a space, then your item text: 1. First item. Each item goes on its own line. The CommonMark specification section 5.3 governs ordered list parsing — only the first item's number sets the starting value; subsequent numbers are ignored in the rendered output.

Can you use the same number for every item in a Markdown ordered list?

Yes. Using 1. for every line — called lazy numbering — is valid CommonMark and produces identical output to sequential numbering. It is the preferred approach for lists you edit frequently because reordering items does not require renumbering.

Why does my Markdown ordered list start at 1 when I set it to start at 5?

Reddit is the main platform that ignores the start attribute and always resets to 1. All other major platforms (GitHub, GitLab, VS Code, Obsidian, Pandoc) honor the first item's number. If your list is on Reddit, the custom start value will not render correctly.

How deep can you nest ordered lists in Markdown?

The CommonMark specification does not impose a depth limit on list nesting. Practically, readability degrades beyond three or four levels, and some renderers produce unexpected visual output at deep nesting. Use four-space indentation at each level for the best cross-platform support.

What is the difference between a tight and a loose ordered list?

A tight ordered list has no blank lines between items — the parser omits <p> tags around item text. A loose list has blank lines between items — the parser wraps each item's content in <p> tags, adding vertical spacing in the rendered output. Mixing tight and loose items in the same list produces a loose list overall per the CommonMark spec.