Looking through the posts on this, I am feeling a bit confused as to what the correct thing is regarding ordered sublists, and the reasoning behind them.
Given this Markdown
1. one
1. one-A
2. two
2. two-A
3. three
CommonMark (0.29.2 via Babelmark2) gives me the output I would expect:
To be clear, this makes perfect sense to me. I typed in 3 list items for the first list, and 2 sublists, one for each of the first two items. To me, this is obvious.
It is when i change the Markdown that I have an issue:
1. one
1. one-A
2. two
2. two-A
3. three
From a obvious point of view, I am now starting the second sublist at 2 instead of 1. In the case where I am providing editing notes for a friend, who often types in lists and sublists for her first draft, this is a perfectly legit notation. I am deliberately skipping the first item in the second list as I do not have any comments on the first item of her second list. Unless I am missing something obvious, to me this is the most reasonable interpretation of this Markdown.
I did follow the conversations about the second sublist and paragraphs from other posts, but can someone please provide a good example of how this output is a more reasonable interpretation of the list I type in than having a second sublist starting at 2?
When the first list item in a list interrupts a paragraph—that is, when it starts on a line that would otherwise count as paragraph continuation text—then
(a) the lines Ls must not begin with a blank line, and
(b) if the list item is ordered, the start number must be 1.
This is trying to avoid parsing arbitrary numbers followed by a period at the start of a line as list items. In some languages, this is standard for ordinal numbers and therefore occurs frequently in dates, e.g. “12. November” in German.
That is a good case. My question is more geared towards whether or not it makes sense rather than “is it in the spec”
So, if I understand correctly:
1. my list
2. my sub-list
is interpreted as 2. my sub-list is an extension of the paragraph started in the main list item 1. my list and not the start or a sub-list. Based on another part of the spec, as an indented code block cannot interrupt a paragraph, it would not be interpreted as an indented code block, but as an extension of the first paragraph. So from a specification point of view, as it is written, I think this is solid.
My question is more around whether or not this fulfils the goal of “readable as-is”.
While I agree that having the above 2. my sub-list could fall into that category of “it may be”, the most obvious reading to me is that it is a sub-list.
I guess I am trying to open a conversation about readability. For me, if it looks like a list, it should act like a list. To me, regardless of any other concern, that Markdown code snippet looks like a list with a sub-list, regardless of what the starting numbers are.
I do understand the Exceptions that Crissov posted, but it seems weird to me that having both numbers on the same line is honored, but starting the inner list on a newline is not. It just seems inconsistent to me.
Just to be clear, I am not arguing for the sake or arguing, just trying to understand things better.
To me, regardless of any other concern, that Markdown code snippet looks like a list with a sub-list, regardless of what the starting numbers are.
That’s only true for your specific example. Consider:
1. The project risked missing
its deadline of March
13. A meeting was called.
2. The architect would take flight
457. It was the red eye.
3. She would stay at the Hilton, room
22. It had an ocean view.
In other words, it’s obvious to humans. So until we can incorporate AI into the markdown parser, we have to settle for an imperfect heuristic.
This is definitely a rough edge, and I’m not 100% happy with the solution we currently have.
If we were inventing a light markup language from scratch, I’d want to require a blank line before a list or sublist (see Beyond Markdown), for this and many other reasons.
But we’re not, so we need to find a compromise that works.