Markdown Avoid Auto Numbering

I spend most of my time doing my writing in markdown. One of the features I have mixed feelings about, is auto-numbering of ordered lists in markdown.

How Ordered Lists Work

The markdown parser will automatically turned a numbered list like:

1. One
2. Two
3. Three

into the HTML

<ol>
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
</ol>

which renders as the following

1. One
2. Two
3. Three

The Leading Number Doesn’t Matter

Because the list is rendered as <ol>/<li> markup, the leading number doesn’t matter. For example

1. One
1. Two
1. Three

Gives you the same rendered result

1. One
2. Two
3. Three

This is Great

This is great because now if you need to re-order your list or insert an item you don’t have to re-number everything.

This is Awful

Sometimes I need my numbers out of order, e.g. for a countdown in preparation for starting a run

3. Put on shoes
2. Open door
1. Step outside

However this will render with the numbers automatically generated.

1. Put on shoes
2. Open door
3. Step outside

I find this problem comes up a lot when I’m working with Issue tickets in Bitbucket or GitHub. Often, I need to reference item 3 from an earlier list but if I write

3. Item three

it renders

1. Item three

The Solution

The solution I’ve found is adding a backslash (\) before the period, which disables the list auto-numbering. For example the markup

3\. Put on shoes
2\. Open door
1\. Step outside

renders

3. Put on shoes
2. Open door
1. Step outside

Limitations

When we escape the period in our list items, we don’t actually get an HTML list instead we get text that looks like a list (e.g. we’re missing the margin that gets applied to lists). Personally, I’m more than happy to give up this margin to get the rendering I want.

Use Markup (in your Markdown)

If it is important that your lists render as proper markup, you can still control the numbering of your lists by using markup in your markdown and using the reversed and start attributes on the ordered list tag (<ol>). (If you want to go this route you can read more about ol tag attributes).

As an example, the markup

<ol start="3" reversed="reversed">
    <li>Put on shoes</li>
    <li>Open door</li>
    <li>Step outside</li>
</ol>

will render as

3. Put on shoes
4. Open door
5. Step outside

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.