[GH-ISSUE #1135] MD029: any interest in zero_one_or_ordered?

kerem commented

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

Owner

Originally created by @dncrews on GitHub (Feb 20, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1135

I'm a big fan of how one and zero work in markdown. I've come across a few situations where zero makes the most sense, even in projects that are usually one-indexed. There doesn't seem to be either "anything is allowed if it's a valid OL in markdown" or "always use the index".

Do you (or anyone else) have interest in having "something" that allows that?

Some possible ideas:

zero_or_one
index_or_ordered or validate_only: this is basically "any of the above"
consistent: I would really like to be able to mix zero & one in a document, and I'm not sure others would expect (Principle of least astonishment) or want that if they used this value, so maybe that's not an answer to my proposal.

I'd be happy to contribute if you think it's worth it.

Originally created by @dncrews on GitHub (Feb 20, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1135 I'm a big fan of how `one` and `zero` work in markdown. I've come across a few situations where `zero` makes the most sense, even in projects that are _usually_ `one`-indexed. There doesn't seem to be either "anything is allowed if it's a valid OL in markdown" or "always use the index". Do you (or anyone else) have interest in having "something" that allows that? Some possible ideas: - `zero_or_one` - `index_or_ordered` or `validate_only`: this is basically "any of the above" - `consistent`: I would really like to be able to mix zero & one in a document, and I'm not sure others would expect ([Principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment)) or want that if they used this value, so maybe that's not an answer to my proposal. --- I'd be happy to contribute if you think it's worth it.

kerem added the

enhancement

label

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

kerem commented

2026-03-07 20:08:03 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 21, 2024):

The existing mode "ordered" allows lists that increment from 0 or 1 - it seems like this is the behavior you are asking for?

@DavidAnson commented on GitHub (Feb 21, 2024): The existing mode "ordered" allows lists that increment from 0 or 1 - it seems like this is the behavior you are asking for?

kerem commented

2026-03-07 20:08:03 +03:00

Author

Owner

@dncrews commented on GitHub (Feb 21, 2024):

Hi @DavidAnson thank you for your time. Let me clarify:

What I'm proposing is either zero_or_one, which would support these:

0. zero
0. indexed
0. lists

or

1. one
1. indexed
1. lists

or index_or_ordered, which would support any of these:

0. zero
0. indexed
0. lists

or

0. zero
1. indexed
2. lists

or

1. one
1. indexed
1. lists

or

1. one
2. indexed
3. lists

Today I can do

Collapsed, since you know what it does, but here in case you want the refresher

With style: "zero" I can do this:

0. zero
0. indexed
0. lists

with style: "one" I can do this:

1. one
1. indexed
1. lists

with style: ordered I can do either of these:

0. zero
1. indexed
2. lists

or

1. one
2. indexed
3. lists

and with style: "one_or_ordered" I can do either of these:

1. one
1. indexed
1. lists

or

1. one
2. indexed
3. lists

@dncrews commented on GitHub (Feb 21, 2024): Hi @DavidAnson thank you for your time. Let me clarify: What I'm proposing is either `zero_or_one`, which would support these: ```markdown 0. zero 0. indexed 0. lists or 1. one 1. indexed 1. lists ``` or `index_or_ordered`, which would support any of these: ```markdown 0. zero 0. indexed 0. lists or 0. zero 1. indexed 2. lists or 1. one 1. indexed 1. lists or 1. one 2. indexed 3. lists ``` Today I can do <details> <summary>Collapsed, since you know what it does, but here in case you want the refresher</summary> With `style: "zero"` I can do this: ```markdown 0. zero 0. indexed 0. lists ``` with `style: "one"` I can do this: ```markdown 1. one 1. indexed 1. lists ``` with `style: ordered` I can do either of these: ``` 0. zero 1. indexed 2. lists or 1. one 2. indexed 3. lists ``` and with `style: "one_or_ordered"` I can do either of these: ``` 1. one 1. indexed 1. lists or 1. one 2. indexed 3. lists ``` </details>

kerem commented

2026-03-07 20:08:03 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 22, 2024):

What's the motivation behind something like zero_or_one as show above? I feel like a person/project may prefer 0s or they may prefer 1s, but they can't prefer both. (In cases where it may not be possible to always use a particular style, rules tend to allow alternatives - but that doesn't seem to be relevant here.) The intent of the rule is to help enforce a standard and allowing both forms seems counter to that.

@DavidAnson commented on GitHub (Feb 22, 2024): What's the motivation behind something like `zero_or_one` as show above? I feel like a person/project may prefer 0s or they may prefer 1s, but they can't prefer both. (In cases where it may not be possible to always use a particular style, rules tend to allow alternatives - but that doesn't seem to be relevant here.) The intent of the rule is to help enforce a standard and allowing both forms seems counter to that.

kerem commented

2026-03-07 20:08:03 +03:00

Author

Owner

@dncrews commented on GitHub (Feb 23, 2024):

Well in this case, the standard I'm trying to require is "use the single number so that we can reorder things as we maintain this documentation; markdown will fix it for you". However, this is an Internal Developer Portal, so sometimes the documentation really should start with 1 (for real life things), and sometimes the list should start with a 0 (for programming things). At the moment, this means we either just can't use ANY standard, or we have to write documentation wrong.

Potentially, this could even be opened up to use an object or an array instead of just style:

MD029:
  supported_formats:
    - zero
    - one
    # - ordered

or

MD029:
  supported_formats:
    ordered: false
    zero: true
    one: true

@dncrews commented on GitHub (Feb 23, 2024): Well in this case, the standard I'm trying to require is "use the single number so that we can reorder things as we maintain this documentation; markdown will fix it for you". However, this is an Internal Developer Portal, so sometimes the documentation really should start with `1` (for real life things), and sometimes the list should start with a `0` (for programming things). At the moment, this means we either just can't use ANY standard, or we have to write documentation wrong. Potentially, this could even be opened up to use an object or an array instead of just `style`: ```yaml MD029: supported_formats: - zero - one # - ordered ``` or ```yaml MD029: supported_formats: ordered: false zero: true one: true ```

kerem commented

2026-03-07 20:08:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 23, 2024):

Maybe you can give an example of a list you would start at 0 instead of 1?

@DavidAnson commented on GitHub (Feb 23, 2024): Maybe you can give an example of a list you would start at 0 instead of 1?

kerem commented

2026-03-07 20:08:04 +03:00

Author

Owner

@dncrews commented on GitHub (Feb 24, 2024):

Items in a Javascript array is a programming example.

One I started using it for was the "you are here" moment that at the beginning of a run-book, which was "read all of the steps of this before starting", kinda like "please listen to the following options, as our menu options have changed".

Not all processes require it, but I've found, for example, that sometimes a step might have to be redone if you didn't realize you needed the output at a later step, and this seemed to help.

@dncrews commented on GitHub (Feb 24, 2024): Items in a Javascript array is a programming example. One I started using it for was the "you are here" moment that at the beginning of a run-book, which was "read all of the steps of this before starting", kinda like "please listen to the following options, as our menu options have changed". Not all processes require it, but I've found, for example, that sometimes a step might have to be redone if you didn't realize you needed the output at a later step, and this seemed to help.

kerem commented

2026-03-07 20:08:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 24, 2024):

The "start with 0" scenario doesn't feel compelling to me. Any list meant for people should probably start at 1. For something like an array, a Markdown list starting at 0 doesn't feel like the right visual. I agree with your proposal above that an object with true/false properties for ordered/zero/one could express the possibilities well, but migrating to that from the current enumeration feels like it could easily confuse people due to the overlap. I'm happy to leave this issue open for others to find and maybe comment on, but I am not in favor of making changes for this at present.

@DavidAnson commented on GitHub (Feb 24, 2024): The "start with 0" scenario doesn't feel compelling to me. Any list meant for people should probably start at 1. For something like an array, a Markdown list starting at 0 doesn't feel like the right visual. I agree with your proposal above that an object with true/false properties for ordered/zero/one could express the possibilities well, but migrating to that from the current enumeration feels like it could easily confuse people due to the overlap. I'm happy to leave this issue open for others to find and maybe comment on, but I am not in favor of making changes for this at present.

kerem commented

2026-03-07 20:08:04 +03:00

Author

Owner

@dncrews commented on GitHub (Feb 27, 2024):

kk cool; the last question in my mind is if there is value in "just make it any one of the proper markdown OL formats" or if you'd rather keep it specific.

@dncrews commented on GitHub (Feb 27, 2024): kk cool; the last question in my mind is if there is value in "just make it any one of the proper markdown OL formats" or if you'd rather keep it specific.

kerem commented

2026-03-07 20:08:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 5, 2024):

The more permissive a rule becomes, the less value it has for enforcing consistency. I don't claim the current implementation is a perfect balance, but there have been very few requests over the years which makes me feel like it strikes a pretty good balance.

@DavidAnson commented on GitHub (Mar 5, 2024): The more permissive a rule becomes, the less value it has for enforcing consistency. I don't claim the current implementation is a perfect balance, but there have been very few requests over the years which makes me feel like it strikes a pretty good balance.

Rows
Columns

[GH-ISSUE #1135] MD029: any interest in zero_one_or_ordered? #2467