• Skip to primary navigation
  • Skip to main content
Sal Ferrarello
  • About Sal Ferrarello
  • Speaking
  • Connect
    Mastodon GitHub Twitter (inactive)
You are here: Home / Dev Tips / Markdown Avoid Auto Numbering

Markdown Avoid Auto Numbering

Last updated on August 26, 2019 by Sal Ferrarello

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

  1. Put on shoes
  2. Open door
  3. Step outside
Sal Ferrarello
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.

Share this post:

Share on TwitterShare on FacebookShare on LinkedInShare on EmailShare on Reddit
Warning! This is a draft, not a finalized post. See full draft disclosure.

Filed Under: Computing, Dev Tips, Draft, Solution Tagged With: Markdown

Reader Interactions

Comments

  1. Lóránt says

    February 7, 2023 at 2:26 pm

    Thank you for this amazing tutorial.

    I find that in my language we ofter do date lists as ex.

    2019. Brussels,
    2020. Paris,
    2022. ….. etc…

    In this context, is there a potential disclaimer in the front matter or in the html classes that bypasses the ordered list algorythm completely?

    Thank you for your input.

    Reply

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Copyright © 2023 · Bootstrap4 Genesis on Genesis Framework · WordPress · Log in