Ordered lists and sublist starts

Spec
#1

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:

<ol>
<li>one
<ol>
<li>one-A</li>
</ol>
</li>
<li>two
<ol>
<li>two-A</li>
</ol>
</li>
<li>three</li>
</ol>

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.

This conflicts with the output for this which is:

<ol>
<li>one
<ol>
<li>one-A</li>
</ol>
</li>
<li>two
2. two-A</li>
<li>three</li>
</ol>

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?

1 Like
#2

Additional piece of information. In going through some more tests, came across this, which does parse the way I would expect it:

1. 2. foo
#3

The both markdown examples in the original post look same, maybe a copy&paste error?

1 Like
#4

Good catch, and to think I double checked it before posting.

The first example should be:

1. one
   1. one-A
2. two
   1. two-A
3. three
#5

spec:

Exceptions:

  1. 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.

#6

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.

Hoping for some good conversation on this…

#7

Back to the one example I added after the original:

1. 2.  abc

this gets parsed as:

<ol>
<li>
<ol start="2">
<li>abc</li>
</ol>
</li>
</ol>

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.

#8

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.

1 Like
StrictMark: Markdown refactored
#9

I think this was the last thread on the topic, which also discusses several alternatives:

1 Like
#10

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.

1 Like