Descending Ordered Lists

I ran into a document the other day that started out:

Top 10 Reasons To Bla Blab

10. reason
 9. reason

Markdown instead numbered the list 1…10 instead 10…1.

Is this to weird or is it something to consider?

That is the expected behavior in the original markdown syntax.

At one point I recall reading something about allowing authors to specify the numbers in a markdown list.

For that feature I would recommend treating it as an extension to the core of markdown.

Without the extension:

 3. three
 2. two
 1. one

should turn into


whereas with the extension, it should turn into:

    <li value="3">three</li>
    <li value="2">two</li>
    <li value="1">one</li>

I would also be inclined to allow for a different numbering syntax when the order matters. The reason the actual numbers are ignored is to support authors being lazy, so that they don’t need to keep track themselves.


 1. a
 1. b
 1. c
 1. d
 1. e
 1. f
 1. g

turns into a list from 1-7, and items can be inserted in the middle without needing to renumber anything.

A syntax like

 5) a
 4) b
 3) c
 2) d
 1) e

could allow for the default behavior to be left as-is, while providing a means to explicitly renumber without resorting to raw HTML.

1 Like

CommonMark makes the starting number significant. However, the remaining numbers are ignored, so your backwards numbered list starting from 10 will come be numbered 10, 11, 12, …

CommonMark already allows ) delimiters on lists, but these aren’t treated differently from . delimited lists.

1 Like

One concern is that adding support for descending ordered lists might break some existing Markdown documents. For example, you might have a list like this (valid Markdown):

2. Item One
1. Item Two

Which is supposed to render as:

  1. Item One
  2. Item Two

In practice, though, how likely is it that Markdown documents would contain descending ordered lists that are not meant to be rendered as descending lists? I’m guessing, not that often unless the author was in hurry and didn’t tidy up the numbering. Support for descending ordered lists might make a good CommonMark extension.

I don’t get it. Why does it have to be an ordered list?

If I write

2. Two
3. Three
5. Five
7. Seven

It should translate to that and not (if you look at the raw here (or in pencil / show history button up there), you’ll see I wrote just same thing):

  1. Two
  2. Three
  3. Five
  4. Seven

Where this weird standard conversion came from, and why does it persist for so long?

Even that doc @zzzzBov pointed does state:

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.

1 Like

@Cawas the weird conversion you write about is HTML ignoring the list item number and producing an ordered list element (which is not stored with numbers). The web browser then inserts the numbers, in ascending order by default. In HTML you can specify that the list should be reserve ordered by adding an attribute to the list as a whole (rather than to individual list items).

@jgm Perhaps descending ordered lists should be part of the core spec? I realise that this would break backward compatibility with a subset of documents, but are these documents not edge cases? In my experience, users are confused when their descending ordered lists are rendered in the opposite direction - if they type a list in descending order they nearly always intend it to be rendered that way.

This could be an extension, but then we’ll have inconsistencies between core and extension CommonMark documents. So it might be better to “fix” this in the core, just as the list marker change was added.

I’m hardly an expert on Markdown, so forgive me if this proposal is horribly flawed or naive, but it seems to me much of the existing behavior could be preserved and carried over to descending-order lists if an optional direction specifier were to be added to the first item.

Borrowing from the spec language, an ordered list would be defined thusly:

An ordered list marker is a sequence of 1–9 arabic digits (0-9), optionally followed by a direction indicator ‘-’ or ‘+’, followed by either a ‘.’ character or a ‘)’ character.

Including a ‘-’ for the direction specifier would indicate the items should be numbered in descending order. The ‘+’ direction specifier would be redundant, and would only serve as a sort of affirmation to human editors that that the direction was chosen deliberately in a context where one might have intuitively expected a descending-order list.

Just as the starting number is derived solely from the first list item, so too would the order direction be derived. Note that I chose to put the specifier after the number to further distinguish it from an ordered list nested within an unordered list item.

Example 1

1-. three  
1. two
1. one


3. three
2. two
1. one

Example 2

3-) three  
4) two
5) one


3. three
2. two
1. one

Example 3

5-. five
1. four
1. three


5. five
4. four
3. three

This of course begs the question of what to do when you have more items than non-negative numbers to count down to, e.g., a descending ordered list starting at 3 but with 6 items. I would suggest mirroring the behavior of <ol reversed>, which, at least in Chrome, is to simply keep counting down past zero and into the negative (e.g., 3, 2, 1, 0, -1, -2).

Now, this solution may not be as intuitive as inferring the direction based on the numbering scheme, but inferring the direction would introduce other issues:

  • If the reversed direction were to be inferred from an exact descending order of numbers (e.g., 5., 4., 3., …), then we would lose the very useful “only the first number counts” policy, and a human editor would have to be careful to update all affected items whenever an item is added or removed. This strikes me as clearly sub-optimal.

  • If the reversed direction were to be inferred from the relative numbering of, say, the first few items, then any descending-order list would need at least two leading items numbered greater than one, e.g., 3) and 2). Specifying 3) followed by 1) would not be sufficient, as that is the same syntax used to denote an ascending-ordered list starting at 5. This would work, but feels a bit clunky to me.

  • Any solution that infers the order could potentially break existing documents. It doesn’t seem incredibly unlikely that an author would end up reversing an already-written list by copying+pasting the already-written items, and since the relative numbering wasn’t important, they may have chosen to leave the item numbers unchanged.

Granted, there is still a risk of breaking compatibility with existing documents. My brief experimentation in the online editor suggests that the number of affected cases would be very small, and unless you have a habit of starting lines with an emote like 8-), then you probably won’t run into issues. And while I feel like this is a fairly unambiguous solution, I concede that most authors will probably need to consult the help/spec upon needing a descending-ordered list the for the first time.

Perhaps we could compare the first and last numbers in the list. If the first is greater than the last, make it descending. The following would produce a descending ordered list (as you would intuitively expect):

5. Five
4. Four
3. Three
2. Two
1. One

The following lazy list would also produce a descending ordered list:

5. Five
1. Four
1. Three
1. Two
4. One