Nested lists render differently in ordered vs. unordered lists

[rhartmann]

Create page with this content:

# Nested lists

- Alfa
  - Bravo
  - Charlie
- Delta

1. Echo
  - Foxtrott
  - Golf
1. Hotel

1. India
   - Juliett
   - Kilo
1. Lima

- Mike
  - November
  - Oscar
- Papa

1. Quebec
   1. Romeo
   1. Sierra
1. Tango

Observe that all indented lists render as nested, with one exception: 2-space indented within an ordered list

I threw this directly at mistune with the same result, so I suppose it is not specific to Otterwiki.

But it is somewhat surprising to me, as it changes the behavior of the nested list not based on it's indentation but based on what kind of list it is nested within. And it disrupts the counting of the outer ordered list.

Is this worth pointing out somewhere, or maybe even modify the rendering?

Note: The "official" Markdown spec demands 4 spaces for nesting into list items.

Screenshot of Otterwiki:

For comparison, this is rendered by GitHub, same effect:

Nested lists

• Alfa
  • Bravo
  • Charlie
• Delta

1. Echo

• Foxtrott
• Golf

1. Hotel

2. India

   • Juliett
   • Kilo

3. Lima

• Mike
  • November
  • Oscar
• Papa

1. Quebec
   1. Romeo
   2. Sierra
2. Tango

[redimp]

Note: The "official" Markdown spec demands 4 spaces for nesting into list items.

I think this is the answer.

With just two spaces nested lists like

1. Echo
  - Foxtrott
  - Golf
1. Hotel

the lists get rendered as

<ol>..</ol>
<ul>..</ul>
<ol>..</ol>

so NOT nested, hence it looks like the counting has been reset.

While lists nested with four spaces like

1. India
   - Juliett
   - Kilo
1. Lima

is rendered correctly as

<ol>
  <li>Hotel</li>
  <li>India
    <ul>
      <li>Juliett</li>
      <li>Kilo</li>
    </ul>
  </li>
<li>Lima</li>
</ol>

[rhartmann]

That is the what confuses me. None of the lists in the example use 4 spaces.

With 3 spaces, they consistently render as nested.
With 2 spaces, it depends on the outer list type.

[redimp]

Uh, its three not four in the second block, my bad.

If this helps, consider it as more then two :D (I'm not cool enough to know the exact quote of Monty Pythons Holy Handgranade of Antioch)

This is the mistune regexp that marks the start of a list:

LIST_START = re.compile(
        r'( {0,3})([\*\+-]|\d{1,9}[.)])(?:[ \t]*|[ \t][^\n]+)\n+'
    )

I'm not concerned enough that this causes bigger problems, but I think it would help to add to An Otter Wiki docs that nested lists need 4 spaces.

[rhartmann]

I think I figured it out. It depends on the indentation of the first character of the outer list item (the "content"), not the indentation of the list item itself.

1. This is at 3
   - At 3, works
 
1.   This is at 4
   - At 3, does not work

1.  This is at 4
    - At 4, works

1.   This is at 5
    - At 4, nope :( this even is plain text, not even a list

1.   This is at 5
     - Test luck

1. This is at 3

   • At 3, works

2. This is at 4

• At 3, does not work

1. This is at 4

   • At 4, works

2. This is at 5
   - At 4, nope :( this even is plain text, not even a list

3. This is at 5

   • Test luck

[redimp]

Holy crap. Uhm. Okay this needs proper documentation.

Hm, maybe sticking to the "official" syntax is the best idea. What do you think?

[rhartmann]

Holy crap. Uhm. Okay this needs proper documentation.

From the renderer perspective, the current behavior makes so much bloody sense. But when authoring Wiki pages, the human perspective seems far more relevant. From there, it's just WTF.

GitHub are aware that John Grubers spec is ambiguous (GFM Spec, 1.3.1):

How much indentation is needed for a sublist? The spec says that continuation paragraphs need to be indented four spaces, but is not fully explicit about sublists. It is natural to think that they, too, must be indented four spaces, but Markdown.pl does not require that. This is hardly a “corner case,” and divergences between implementations on this issue often lead to surprises for users in real documents.

The GitHub Flavored Markdown Spec is clear about it (GFM Spec, 5.2, a little above Example 272):

A sublist must be indented the same number of spaces a paragraph would need to be in order to be included in the list item.

Hence, the same amount of indentation as the first character of the list item content. Example 274 shows a wide list marker 10) that requires sublists with four space indentation. Long lists with 100) and beyond need five spaces etc. Example 276 makes it even more clear why that makes sense from the spec perspective: A sublist may be the first content block of a list item. With this, the sublist indentation ultimately depends on the outer list. Though that writing style seems straight up evil to me.

The GFM spec seems to be based on the CommonMark spec. The above text passages and examples can be found there as well.

So the current mistune behavior regarding sublists seems to follow the CommonMark / GitHub flavor, though I don't know if that is on purpose.

Hm, maybe sticking to the "official" syntax is the best idea. What do you think?

IMHO, list nesting should be configurable, defaulting to four spaces as per spec I don't even know anymore what should be default, but allowing two spaces as well. Maybe also provide a CommonMark option that would give the current behavior for not breaking existing installations.

I did some more tests with the example snippet above:

• python-markdown renders the entire example as a flat unordered list, nothing nested
• python-markdown2 renders all indented items as nested

So, yeah, neither follows CommonMark. Guess you have free choice.

It's a mess.