Ordered Lists
An ordered list is the syntax you reach for when order carries meaning: the steps of a procedure, the order of troubleshooting checks, a ranked checklist, a set of acceptance criteria. The syntax looks like the unordered list with a number in front, and that is exactly where the surprise starts. The number you type is not the number the reader sees. The renderer counts the items itself and renumbers them, so a list you wrote as 1, 2, 3 can end up on the page as 1, 2, 3, 4 after you insert a fourth step in the middle, and the source file never has to be touched again.
This page explains how that works, which single number in the list is not ignored, and the one rule that decides whether a numbered line becomes a list at all or stays part of the paragraph above it. It also covers the two markers you can use, how nested ordered lists are numbered, and the trap that makes a line such as 2024. a plan for the year behave differently depending on what comes before it.
Write a number, a delimiter, a space, and then the item text:
1. Install the dependencies
2. Configure the environment
3. Start the development server<ol>
<li>Install the dependencies</li>
<li>Configure the environment</li>
<li>Start the development server</li>
</ol>The right parenthesis is a second legal marker: 1), 2), 3) produce exactly the same <ol>. Use whichever one your team prefers, but do not mix the two inside a list. Changing the delimiter, exactly like changing an unordered marker, starts a new list instead of continuing the old one:
1. Dot marker
1) Parenthesis markerThe page shows two separate <ol> elements, one after the other, not one list with two items. A space must follow the marker, just as with an unordered list. 1.Install is not a list item; it is a paragraph that happens to begin with a number.
This is the rule worth remembering. The numbers in the source are decoration for you, not for the reader. The renderer only knows that this is an ordered list and that it has three items, and it assigns the labels itself:
1. Install the dependencies
1. Configure the environment
1. Start the development serverThe result on the page is identical to writing 1, 2, 3. Two practical consequences follow. Inserting a step in the middle costs exactly one line, because you give the new step any number you like and everything after it shifts down by itself. Deleting a step also costs one line, because the remaining numbers close the gap, so you can never end up with 1, 2, 4, 5 that has to be repaired by hand.
That is why most projects still write the real numbers in the source even though they are ignored: the source stays readable for the person editing it, and a diff shows that step three became step four instead of showing one unexplained added line. What you must not do is treat the numbers in the source as the numbers on the page, or spend time renumbering by hand after every edit.
The first number of a list is the exception. It sets the starting value:
3. The third step is really the first
4. The next step<ol start="3">
<li>The third step is really the first</li>
<li>The next step</li>
</ol>Every other number in the list is ignored. The 4 above is not read as “the number four”; the renderer simply makes the second item the successor of the first. The same first number also decides whether the list may interrupt a paragraph. A numbered line may start a list in the middle of a paragraph only when that first number is 1, which is why a line such as 2024. a plan for the year stays a lazy continuation of the paragraph above it instead of becoming a list with start="2024". At the start of a block, where no paragraph waits to be continued, the very same line does become a list with start="2024". The rule exists to keep sentences that begin with a year out of the list machinery.
Ordered lists nest like any other list, and the nested list is always numbered from 1 again, whatever number the parent carries:
1. Install the dependencies
1. Run `pnpm install`
2. Commit the lockfile
2. Start the development server<ol>
<li>Install the dependencies
<ol>
<li>Run <code>pnpm install</code></li>
<li>Commit the lockfile</li>
</ol>
</li>
<li>Start the development server</li>
</ol>The child has to be indented to the column where the parent item’s text starts, which is the fourth column, three columns in from the left margin, so three spaces are enough here. When the parent number grows to two digits the content moves to column five and the child has to move four spaces to the right, which is the same rule the next page states in full: the indentation is measured from the width of the marker, not from the number of spaces you happen to feel like typing.
| Written as | Actually renders as | Why |
|---|---|---|
1. Step | a list item | the base form |
1.Step | plain text | a space must follow the marker |
1. Step then 1) Step | two separate lists | changing the delimiter starts a new list |
a paragraph followed by 2. Step | more paragraph text | only a list starting at 1 can interrupt a paragraph |
The numbers in the source do not describe the order on the page. Because the renderer ignores them, a list that reads 1. 2. 3. in the file may be displayed as 1. 2. 3. 4. after an insertion, and a colleague reading the source cannot tell the current order from the source alone. The fix is not to renumber by hand, which only hides the discrepancy until the next edit, but to keep the source numbers in step with the intended order so that the file stays truthful to a human reader. Never quote the source numbers when you need to refer to a specific step; refer to the step by its content instead.
Rewrite the following plain text as Markdown. Use one ordered list for the four steps, keep the first number at 1 so that the list can interrupt the paragraph above it, nest one sub-step under the second step, and indent the sub-step to the column where the parent item’s text starts.
Prepare the release
Run the checks
Tag the commit
Publish the package
Announce the releaseApproach:
The four steps are sequential, so they belong in one ordered list. The first number has to be 1, because only a list that starts at 1 is allowed to interrupt a paragraph; the remaining numbers are free, since the renderer assigns the labels itself. The sub-step is a child of the second item, and a child is expressed by indenting it to the column where the parent’s content begins, which is three columns past the 1. marker.
Steps:
- Write each of the four steps as a number, a period, a space, and the text, numbering them 1, 2, 3, 4 so that the source stays readable.
- Keep the first number at 1, otherwise the whole list is swallowed by the paragraph above it.
- Indent the sub-step by three spaces and give it its own number, a period, and a space, so that it lines up with the parent’s text column, then check that the result is a four-item list numbered 1 to 4 with one nested item under the second step.
Answer:
1. Prepare the release
2. Run the checks
1. Tag the commit
3. Publish the package
4. Announce the releaseYou can now write an ordered list with either the 1. or the 1) marker, and you know that the numbers in the source are ignored by the renderer, so inserting or removing a step never requires renumbering. You know that the first number is the exception that sets the start value and that a list may only interrupt a paragraph when that first number is 1. You also know that a nested ordered list always restarts at 1 and that its indentation is measured from the width of the parent’s marker. The next page turns to nesting itself, and the rule that decides at which column a child list begins.