MD029: any interest in zero_one_or_ordered?

[dncrews]

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.

[DavidAnson]

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

[dncrews]

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

[DavidAnson]

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.

[dncrews]

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

[DavidAnson]

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

[dncrews]

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.

[DavidAnson]

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.

[dncrews]

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.

[DavidAnson]

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.