Enumerated lists don't need to start with 1, however... about markdown-guide

[mattcone]

Open to suggestions on this one.

FWIW, I do think the "How Does it Work?" section needs some revision. I'm also planning on adding an entire "Extended Syntax" section with information about the various lightweight markdown languages. But I don't know... maybe the markdown languages need a shoutout earlier in the guide.

[mattcone]

Thanks for raising this as an issue! My (admittedly limited) understanding is that this is kind of a gray area. Gruber himself noted in his original design document that it's a good idea to start with the number one:

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.

Sure enough, the Bablefish 2 tool reveals that a number of Markdown implementations start the list with the first number used. Take the following list for example:

4. hi
9. hello
1. hey

You can see the results here. CommonMark and several other implementations start the list with the <ol start="4"> tag, which means the list will start with the number four. I tested this in Dillinger (which uses a CommonMark implementation), and the list does start with the number four. The other implementations still start the list at number one.

Very confusing!

I'm not quite sure how to communicate stuff like this. I'm working on a troubleshooting section, but there are so many gray areas like this that it's probably impossible to note them all.

In this particular case, my personal opinion is that if you want the list to start with the number one, you should start the list with the number one. It's not required for all implementations, but it's a best practice that can prevent unexpected issues down the road if you move your Markdown files into another application.

[gaylin]

Actually I think it would be immensely useful to have a gray area information section even if it's only to show the most troublesome things people run into. If the list started to get obscenely long, I suppose it could always get moved to another page or something. But even if it only focused on the chief offenders for the time being, I think it would be of use.

What about keeping the comment as is right now, and then when the troubleshooting or "gray area" is created, place it at the bottom of the guide and link inline to it? Something like this...

The numbers don’t have to be in numerical order, but the list should start with the number one
(though read more about gray areas when formatting numbered lists).