Pro Tip: Use “1.” for Every Ordered List Item when Writing Markdown

A quick tip for making ordered lists in markdown easier to write.

When authoring an ordered list, I have a natural tendency to add the proper integers that set the order. Like this:

1. Do this first.
2. Then this.
3. Do this third.
4. And this last.

And, as you might expect, that compiles to the following HTML:

<li>Do this first.</li>
<li>Then this.</li>
<li>Do this third.</li>
<li>And this last.</li>

Do you notice a funny discrepancy? Although we specified the order of the items, Markdown compilers lead to markup that designates the structure. The proper number values are set by the browser interpreting the HTML.

Number Values Don’t Matter for Ordered Lists

That’s right! According to the original spec:

It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces.

This means you can use any numbering and still get the same result. If you do this:

1. Do this first.
1. Then this.
1. Do this third.
1. And this last.

Or even this:

5. Do this first.
6. Then this.
7. Do this third.
8. And this last.

You end up with the same resulting HTML.

Start with Number 1

That said, it’s still important to start with 1.. Per the spec:

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

Use Number 1 Exclusively

Given the above, I personally love to use 1. exclusively for ordered list items.

1. Do this first.
1. Then this.
1. Do this third.
1. And this last.

I like this because it reduces the amount of cognition needed to both read and write markdown. If I see 1. I know it’s an ordered list. My brain knows the items are sequential. Most of the time, that’s good enough.

I also find it easier to edit. Just as with unordered lists, you can move items around and not need to change the character that dictates its structure. This is just as it would be if you were authoring HTML, and the whole point of markdown is that it’s an easier way to write content that is transformed into HTML code.

Exceptions to the Rule

That said, there is a primary exception to this pattern. If the value of the number is significant, then I number accurately. This usually means if I’m going to reference the number itself in content, then I want to write that number out.

This is technically still error-prone and not a foolproof solution, but it becomes a trigger to me to do more careful editing.

Let's Connect

Keep Reading

Use Commit Hashes when Sharing GitHub URLs

Sharing GitHub commit hashes directly works for ephemeral uses, but there is a safer way for links that need to last.

Dec 15, 2022

MDX: Benefits, Challenges, & Use Cases

MDX is undeniably powerful. It gives developers an excess of flexibility and efficiency in authoring content. But it has enough challenges that suggest we may be ready for something better.

Sep 06, 2022

Run a Single Jest Test

Learn how to run a single test within a file, how to target a series of tests within a file, or how to only target a single file when using Jest.

Jun 04, 2022