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
- One
- Two
- 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
- One
- Two
- 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.
- Put on shoes
- Open door
- 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
- 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
- Put on shoes
- Open door
- Step outside
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.
Can someone please start a petition to remove this “feature” from all markdown implementations?
If you use this syntax:
1. first
1. second
1. third
Then yes, it should auto-number them. That’s useful.
But if you use this syntax:
3. third
4. fourth
5. fifth
Then it should generate
Third
Fourth
Fifth
not
Third
Fourth
Fifth
which violates the principle of least astonishment.
And if you say
3. third
5. fifth
6. sixth
It should generate
Third
Fifth
Sixth
Can we consider this a bug in the markdown specification and get implementations to fix it?