[GH-ISSUE #137] Nested lists: why 2 spaces for unordered lists, 4 spaces for ordered lists?

kerem commented

2026-03-07 20:03:11 +03:00

Owner

Originally created by @gandalfsaxe on GitHub (Jul 18, 2018).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/137

Why are there difference in the required spaces for ordered/unordered lists? The following will work fine:

* one
* two
* three
  * sub1
  * sub2

1. one
2. two
3. three
    1. sub1
    2. sub2

But change the 2 spaces to 4 i in the first list, or the 4 spaces to 2 in the second list, and it will give a warning. Why not consistence?

Originally created by @gandalfsaxe on GitHub (Jul 18, 2018). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/137 Why are there difference in the required spaces for ordered/unordered lists? The following will work fine: ```markdown * one * two * three * sub1 * sub2 1. one 2. two 3. three 1. sub1 2. sub2 ``` But change the 2 spaces to 4 i in the first list, or the 4 spaces to 2 in the second list, and it will give a warning. Why not consistence?

kerem

2026-03-07 20:03:11 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:03:12 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 19, 2018):

The intent is that all the lines of list item content are aligned the same. The different widths of ordered/unordered list item prefixes makes it seem inconsistent.

Your first example is correct, but the second should really use three spaces. Markdown is very forgiving, so being a little off usually "just works".

The CommonMark specification explains this in more detail: https://spec.commonmark.org/0.28/#list-items

@DavidAnson commented on GitHub (Jul 19, 2018): The intent is that all the lines of list item content are aligned the same. The different widths of ordered/unordered list item prefixes makes it seem inconsistent. Your first example is correct, but the second should really use three spaces. Markdown is very forgiving, so being a little off usually "just works". The CommonMark specification explains this in more detail: https://spec.commonmark.org/0.28/#list-items

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@gandalfsaxe commented on GitHub (Jul 20, 2018):

Thanks for your answer. The section in the CommonMark is quite dense and goes into a lot of things, including indented paragraphs in general, but I found the relevant section here right below this example: https://spec.commonmark.org/0.28/#example-256

So as I understand it: the CommonMark spec's point of referenec is that it wants two spaces of indentation for sublists. However due to the fact the numbered lists have an extra character compared to unordered lists (* vs. 1. ), we want three spaces in numbered sublists.
In other words, we care more about visually indentation than the number of spaces being the same in both kinds of sublists, correct?

I don't know if I like this. Seems to over-emphasize the visual appearance at the cost of simplicity. The difficulty for me comes in when I'm working with markdown in practice in editors (in my case VSCode) that support a fixed settings of 2 or 4 spaces of indentation. Any solution to this? It seems very sub-optimal to have to think and manually insert the correct number of spaces for sublists when writing markdown.

@gandalfsaxe commented on GitHub (Jul 20, 2018): Thanks for your answer. The section in the CommonMark is quite dense and goes into a lot of things, including indented paragraphs in general, but I found the relevant section here right below this example: https://spec.commonmark.org/0.28/#example-256 So as I understand it: the CommonMark spec's point of referenec is that it wants two spaces of indentation for sublists. However due to the fact the numbered lists have an extra character compared to unordered lists (`* ` vs. `1. `), we want three spaces in numbered sublists. In other words, we care more about visually indentation than the number of spaces being the same in both kinds of sublists, correct? I don't know if I like this. Seems to over-emphasize the visual appearance at the cost of simplicity. The difficulty for me comes in when I'm working with markdown in practice in editors (in my case VSCode) that support a fixed settings of 2 or 4 spaces of indentation. Any solution to this? It seems very sub-optimal to have to think and manually insert the correct number of spaces for sublists when writing markdown.

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 20, 2018):

Markdown's original intent was to be visually easy to read and interpret, so I think the conventions are sensible and consistent with that.

However, you can still get what you want by taking advantage of the behavior shown in example 221 and discussed in the paragraph above: https://spec.commonmark.org/0.28/#example-221

Specifically, if you provide extra space after the list marker, you can change the indent to the next multiple of 2. Unordered lists are fine by default, but you can add a single extra space after ordered list items to create an indent of 4.

@DavidAnson commented on GitHub (Jul 20, 2018): Markdown's original intent was to be visually easy to read and interpret, so I think the conventions are sensible and consistent with that. However, you can still get what you want by taking advantage of the behavior shown in example 221 and discussed in the paragraph above: https://spec.commonmark.org/0.28/#example-221 Specifically, if you provide extra space after the list marker, you can change the indent to the next multiple of 2. Unordered lists are fine by default, but you can add a single extra space after ordered list items to create an indent of 4.

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@gandalfsaxe commented on GitHub (Jul 22, 2018):

Yeah fair enough, that's also why I like to use Markdown so much. It's completely replaced LaTeX for me (thanks to pandoc).

Two questions now:

Then actually, markdownlint should be changed right? Because it accepts both 3 and 4 spaces like this:

1. one
2. two
   1. sub1
   2. sub2

1. one
2. two
    1. sub1
    2. sub2

Whereas it should really only accept the first example with three spaces and give a warning on the second?

Any suggestion on how to follow this rule in VSC? Because you just set X spaces on editor level, which is what will be inserted in a numbered list when you press tab. To illustrate:

I'm guessing this is something I should take up with the Markdown All in One extension that handles the auto list editing for markdown? Just curious how you deal with this personally.

@gandalfsaxe commented on GitHub (Jul 22, 2018): Yeah fair enough, that's also why I like to use Markdown so much. It's completely replaced LaTeX for me (thanks to pandoc). Two questions now: 1. Then actually, markdownlint should be changed right? Because it accepts both 3 and 4 spaces like this: ```markdown 1. one 2. two 1. sub1 2. sub2 1. one 2. two 1. sub1 2. sub2 ``` Whereas it should really only accept the first example with three spaces and give a warning on the second? 2. Any suggestion on how to follow this rule in VSC? Because you just set X spaces on editor level, which is what will be inserted in a numbered list when you press tab. To illustrate: ![](https://i.imgur.com/JAClaS9.gif) I'm guessing this is something I should take up with the [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) extension that handles the auto list editing for markdown? Just curious how you deal with this personally.

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 22, 2018):

For your first question, I think that behavior would be covered by a rule that does not exist, the counterpart to MD007/ul-indent. I'm not sure if this rule is missing for historical reasons or because it is tricky to implement, but without it I don't think any other rule would report a violation for what you show because both approaches are valid (because it is OK to indent a list item an extra space). (FYI, I made this a bit more flexible in recent commit github.com/DavidAnson/markdownlint@4a1e42d942.)

For your second question, that's not something I remember running into. I'm not at my computer now, but maybe I subconsciously fix the first sublist indent and then VS Code uses the same indent for subsequent lines? At any rate, the extension you point to seems like the right place to try to enforce correct and consistent tabbing. (I wasn't aware of it before now, thank you for pointing it out!)

@DavidAnson commented on GitHub (Jul 22, 2018): For your first question, I think that behavior would be covered by a rule that does not exist, the counterpart to `MD007/ul-indent`. I'm not sure if this rule is missing for historical reasons or because it is tricky to implement, but without it I don't think any other rule would report a violation for what you show because both approaches are valid (because it is OK to indent a list item an extra space). (FYI, I made this a bit more flexible in recent commit https://github.com/DavidAnson/markdownlint/commit/4a1e42d942136b1546c22e428dfb9102bc1b226b.) For your second question, that's not something I remember running into. I'm not at my computer now, but maybe I subconsciously fix the first sublist indent and then VS Code uses the same indent for subsequent lines? At any rate, the extension you point to seems like the right place to try to enforce correct and consistent tabbing. (I wasn't aware of it before now, thank you for pointing it out!)

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@gandalfsaxe commented on GitHub (Jul 22, 2018):

I'm not sure if this rule is missing for historical reasons or because it is tricky to implement

I thought you were in charge of the rules? :-)

Second question: Hmm ok.. seems like there is no good solution at the moment then. Because using 4 spaces always will cause MD007 to trigger, and using 2 spaces always will trigger MD005+MD029 + will not render in GFM (e.g. in these very comment fields). Thus I have to insert spaces manually (which breaks the typing flow) or hope that "Markdown All in One" will implement it.

It also means that I now have to take a closer look at all the other markdown editors I use. Curiously, Typora has a good implementation; 2 spaces for unordered sublists, 3 spaces for ordered sublists. Caret on the other hand, just uses 4 spaces for all sublists.

Looks like I'm opening issues for both Caret and Markdown All in One. And inserting an extra space manually for now.

@gandalfsaxe commented on GitHub (Jul 22, 2018): > I'm not sure if this rule is missing for historical reasons or because it is tricky to implement I thought you were in charge of the rules? :-) Second question: Hmm ok.. seems like there is no good solution at the moment then. Because using 4 spaces always will cause MD007 to trigger, and using 2 spaces always will trigger MD005+MD029 + will not render in GFM (e.g. in these very comment fields). Thus I have to insert spaces manually (which breaks the typing flow) or hope that "Markdown All in One" will implement it. It also means that I now have to take a closer look at all the other markdown editors I use. Curiously, [Typora](https://typora.io) has a good implementation; 2 spaces for unordered sublists, 3 spaces for ordered sublists. [Caret](https://caret.io) on the other hand, just uses 4 spaces for all sublists. Looks like I'm opening issues for both Caret and Markdown All in One. And inserting an extra space manually for now.

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 22, 2018):

The original set of rules came from the Ruby implementation and I wasn’t involved in the early decision-making.

I’ll probably close this issue soon since it seems more about editor behavior at this point. If you want to open an issue for ol-indent, go for it - but it may end up getting in your way later if you try tip-off standardize on 4 spaces. :)

@DavidAnson commented on GitHub (Jul 22, 2018): The original set of rules came from the Ruby implementation and I wasn’t involved in the early decision-making. I’ll probably close this issue soon since it seems more about editor behavior at this point. If you want to open an issue for `ol-indent`, go for it - but it may end up getting in your way later if you try tip-off standardize on 4 spaces. :)

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@gandalfsaxe commented on GitHub (Jul 22, 2018):

I think it would make sense to have a ol-indent when we have a ul-indent. I don't see any reason why ordered lists should be allowed to be indexed by 4 spaces when ordered isn't. Any thoughts on this? Otherwise I'll open an issue for that. In any case, yeah I'd say we can close this now.

EDIT: I just realized I didn't understand this:

but it may end up getting in your way later if you try tip-off standardize on 4 spaces. :)

@gandalfsaxe commented on GitHub (Jul 22, 2018): I think it would make sense to have a `ol-indent` when we have a `ul-indent`. I don't see any reason why ordered lists should be allowed to be indexed by 4 spaces when ordered isn't. Any thoughts on this? Otherwise I'll open an issue for that. In any case, yeah I'd say we can close this now. EDIT: I just realized I didn't understand this: > but it may end up getting in your way later if you try tip-off standardize on 4 spaces. :)

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 22, 2018):

No objections, go ahead and open it. Thanks!

@DavidAnson commented on GitHub (Jul 22, 2018): No objections, go ahead and open it. Thanks!

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@gandalfsaxe commented on GitHub (Jul 24, 2018):

@DavidAnson you seem to have some experience with CommonMark. If you have any suggestions or advice, it would be lovely if you could chime in at prettier/prettier/issues/4114

@gandalfsaxe commented on GitHub (Jul 24, 2018): @DavidAnson you seem to have some experience with CommonMark. If you have any suggestions or advice, it would be lovely if you could chime in at prettier/prettier/issues/4114

kerem commented

2026-03-07 20:03:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 25, 2018):

I'm afraid I don't have any good suggestions for that issue. I agree with you that 2 spaces after the ordered list marker doesn't look as good and that lists of 10 or more items seem uncommon, BUT I appreciate the tabbing scenario they are trying to handle without breaking existing documents. To my thinking, code fences are better because they are more explicit, but there are plenty of places that don't use them.

@DavidAnson commented on GitHub (Jul 25, 2018): I'm afraid I don't have any good suggestions for that issue. I agree with you that 2 spaces after the ordered list marker doesn't look as good and that lists of 10 or more items seem uncommon, BUT I appreciate the tabbing scenario they are trying to handle without breaking existing documents. To my thinking, code fences are better because they are more explicit, but there are plenty of places that don't use them.

kerem referenced this issue

2026-03-07 20:14:56 +03:00

[PR #1965] [MERGED] Update test repository snapshots. #3680

Rows
Columns

[GH-ISSUE #137] Nested lists: why 2 spaces for unordered lists, 4 spaces for ordered lists? #1965