Alternative (1) ordered list syntax

John Gruber’s syntax guide defines the ordered list syntax as follows:

Ordered lists use numbers followed by periods:

  1. Bird
  2. McHale
  3. Parish

Unlike the unordered list syntax, there is only one variation.

However, it is common for writers to use brackets to define list items instead of periods. My suggestion is to add two variations to the ordered list syntax:

  1. Bird
  2. McHale
  3. Parish


(1) Bird
(2) McHale
(3) Parish

This syntax has likely been implemented in other Markdown flavours already, but I think we should discuss if and how it should be added to CommonMark - as an extension or as part of the core syntax?

This suggestion applies to letter-order lists as well.


It looks like 1) style lists are already mentioned in the spec. I’m not sure about (1) style.

1 Like

I wouldn’t support (1) since 1) is already there and is more common.

Is there a reason not to use (1) as well? The writer may wish to use this style.

Making the people writing the parser easier. I’d restrict it to a single way (e.g. only 1.) even.

I take the view that it is better to make the parser more complicated if it makes life easier for the writer. This is consistent with Markdown’s approach elsewhere. E.g. with unordered lists, some writers may find it more intuitive to use *, for others - is more natural.

1 Like
  1. making the parser fast makes the user life easier.
  2. making the syntax small makes the user life easier.
  3. adding a seldomly used variant of an already supported feature might not help much if it goes against 1 and 2.


(1) is more typing
(2) is surely more visually apparent
(3) might be (more) noisy though ().

Computers are fast and are only going to get faster. Parsing a Markdown file does not seem like a process that would be particularly resource intensive.

Are their real world examples of slow Markdown parsers causing performance issues?

In this case, the writer already knows the three different variations because they are used outside of Markdown. All three variations are used in books, articles, manuals, etc. By supporting all three variations, if the writer intends to write an ordered list there is a good chance that she or he is going to use one of the three formats. That’s without looking at a Markdown syntax guide. If we require the writer to check which variation is supported, we’ve made their life harder.

I think that’s okay. No one is being forced to use (1) instead of 1) or 1. All three would be supported, so you could choose a variation that requires less typing. It’s like how you don’t have to use unlined headings, but they are an option if that visual preference is a priority over quickness of typing. It’s quite a subjective decision.

Yes, plenty =) Anything that renders a page from markdown from a website e.g. flask-flatpages.

btw we also have *1 1> <1> and an another arbitrary amount of different markups to signal ordered lists, I wouldn’t consider all of them.

It would be good to see some stats on this. Maybe adding this particular feature wouldn’t degrade performance significantly.

Are these examples commonly used though? I don’t recognise them from any texts I’ve read. 1., 1), and (1) seem to be the most common (along with Roman numerals).

Note the 1) syntax is already supported

+1 adding ‘(1)’, perhaps as (part of) a flavor extension

as long as there aren’t major implementation headaches involved, which the dev’s would of course be aware of more than most of us

1 Like

(1) would map to ① btw.

What is the use case for ?

This looks a lot more like a footnote or something alike, rather than an ordered list. I’ve never seen this syntax, either in markdown, or elsewhere, except for lists with not linebreak between items.

1 Like

Apple Pages auto creates new list items for all three ordered list types:

Microsoft Word behaves the same way:

And (again) they are both wrong and propagating this won’t make it any right.

© ™ (1) (2) … all map to unicode entities if you really want to parse them and while surely ① would work great for ordered lists, I’m not convinced that it should be core commonmark. Probably adding it to the extra flavour would be a good idea.

While it doesn’t really matter much, I recently noticed that in the email “Request for input: text/markdown media type”, there is a list that looks like:

(2) ...etc...
(3) The solution in (2) above further raises the question ...

Where (2) is used as an inline ‘visual reference’ to a list item number. So for some writers it’s probably done for stylistic consistency.


I raised a question earlier about the use case for ①; I’ll wait for response to that before discussing the point about mapping to unicode characters.

Huh? Is this in the CommonMark spec anywhere? I’m pretty sure I did not see this when I read the spec yesterday?

As for the problem at hand - I’d welcome the use of (1) as a ordered list bullet, it actually looks nice to me. Especially the example @mofosyne gives, referring back to an earlier number in running text is IMHO nicer as (1) than using 1. above or 1) above.

The counterargument to this, though, is that this looks good in markdown source, but in the rendered HTML, the list will always (at least usually) end up having 1. markers, which then no longer correspond with the (1) backreference…

1 Like

I think that’s fine. The styling could be changed with CSS anyway. Consider this example:

<ol type="1">

Any of the three numeric ordered lists could output this HTML. The web designer could then customise the appearance of the ordered list, for example by adding a zero to the front of each list item with CSS:

ol {
  list-style-type: decimal-leading-zero;

Because Markdown and HTML are agnostic about how elements are presented, this is fine. They could even change it to Roman numerals (list-style-style: lower-roman) or a number of other list styles. The designer could even change the numbers to bullets (normally used in unordered lists).

The reason for having (1) is not because it needs to map 1:1 with the output, but rather for predictability while writing it.

1 Like