[GH-ISSUE #97] Ordered list MD029 change from "one" to "ordered" by default #1929

New issue

Closed

opened 2026-03-07 20:02:51 +03:00 by kerem · 4 comments

kerem commented

2026-03-07 20:02:51 +03:00

Owner

Originally created by @prokopst on GitHub (Dec 7, 2017).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/97

Hello!

I have a philosophical "problem" with rule MD029 and its default mode one.

The official markdown introduction states:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

https://daringfireball.net/projects/markdown/

And the syntax part states:

The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.

https://daringfireball.net/projects/markdown/syntax#list

In my opinion, based on the official Markdown docs, recommending one by default contradicts what I like about Markdown - "as readable as possible" and "should be publishable as-is". The laziness factor sounds more like nice to have, not a recommendation.

So I'm kindly asking for a permission to change the default value from one to ordered.

Originally created by @prokopst on GitHub (Dec 7, 2017). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/97 Hello! I have a philosophical "problem" with rule MD029 and its default mode `one`. The official markdown introduction states: > The overriding design goal for Markdown’s formatting syntax is to make it *as readable as possible*. The idea is that a Markdown-formatted document *should be publishable as-is*, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. <https://daringfireball.net/projects/markdown/> And the syntax part states: > The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. *But if you want to be lazy, you don’t have to.* <https://daringfireball.net/projects/markdown/syntax#list> In my opinion, based on the official Markdown docs, recommending `one` by default contradicts what I like about Markdown - "as readable as possible" and "should be publishable as-is". The laziness factor sounds more like nice to have, not a recommendation. So I'm kindly asking for a permission to change the default value from `one` to `ordered`.

kerem

2026-03-07 20:02:51 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-07 20:02:52 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 7, 2017):

Philosophically, I agree with you and would have made this change myself, BUT it is a significant breaking change that would require nearly everyone today to change their documents or settings. That is a high cost for a linting tool, especially for people who don’t care as much about this as we do.

One alternative would be to default the rule to “off” and have everybody opt into the behavior they want. This would not be breaking, but would deviate slightly from the original Ruby implementation. However, many people would not realize this rule was not running and therefore would not benefit from it.

But this is the best idea I have had so far.

@DavidAnson commented on GitHub (Dec 7, 2017): Philosophically, I agree with you and would have made this change myself, BUT it is a significant breaking change that would require nearly everyone today to change their documents or settings. That is a high cost for a linting tool, especially for people who don’t care as much about this as we do. One alternative would be to default the rule to “off” and have everybody opt into the behavior they want. This would not be breaking, but would deviate slightly from the original Ruby implementation. However, many people would not realize this rule was not running and therefore would not benefit from it. But this is the best idea I have had so far.

kerem commented

2026-03-07 20:02:52 +03:00

Author

Owner

@prokopst commented on GitHub (Dec 8, 2017):

@DavidAnson thanks for the response. What about introducing a third, default option to recognize both as valid? For example something like one-or-ordered which would recognize both approaches as valid, but still anything else invalid.

It would deviate from the Ruby solution too though.

@prokopst commented on GitHub (Dec 8, 2017): @DavidAnson thanks for the response. What about introducing a third, default option to recognize both as valid? For example something like `one-or-ordered` which would recognize both approaches as valid, but still anything else invalid. It would deviate from the Ruby solution too though.

kerem commented

2026-03-07 20:02:52 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 8, 2017):

I like this idea!

@DavidAnson commented on GitHub (Dec 8, 2017): I like this idea!

kerem commented

2026-03-07 20:02:52 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 11, 2017):