starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 01:05:55 +03:00

[GH-ISSUE #141] MD007: default value of 2 vs. 4 spaces #119

New issue

Closed

opened 2026-03-03 01:23:53 +03:00 by kerem · 5 comments

kerem commented

2026-03-03 01:23:53 +03:00

Owner

Originally created by @borekb on GitHub (Aug 11, 2018).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/141

Due to related discussions, e.g., https://github.com/careteditor/issues/issues/782 or https://github.com/neilsustc/vscode-markdown/issues/241, I wanted to ask about the history of MD007 rule. After a brief research, it seems to me that:

2 spaces are generally considered nicer (I agree)
2 spaces cause issues in practice – there are major implementations that don't render nested lists with 2 spaces as nested, for example, BitBucket doesn't support two spaces.
CommonMark tutorial and StackOverflow help state 4 spaces.
jgm says about two-space indents: "I think it’s incredibly bad advice for a style guide. Many implementations don’t allow a two-space indent for a sublist (and as I’ve noted above, none allow it consistently). Gruber’s original syntax description says nothing about a two-space indent, and hints at a four-space rule, which many implementations follow. A style guide should encourage a style that will work well across implementations, and a four-space indent for sublists is the best advice for portability."

The rule description even mentions the tradeoffs but I still find it a bit strange that aesthetics would be chosen over functionality. The question I wanted to ask is whether you'd make the same choice today. I personally don't mind the default too much, the main thing for me is that it is customizable (which I always do), I just wanted to learn more about the context as it seems that markdownlint is used as one of the arguments for 2-spaced nested lists in the discussions mentioned above.

Thanks!

Originally created by @borekb on GitHub (Aug 11, 2018). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/141 Due to related discussions, e.g., https://github.com/careteditor/issues/issues/782 or https://github.com/neilsustc/vscode-markdown/issues/241, I wanted to ask about the history of [MD007](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md007) rule. After a brief research, it seems to me that: - 2 spaces are generally considered nicer (I agree) - 2 spaces cause issues in practice – there are major implementations that [don't render nested lists with 2 spaces as nested](https://babelmark.github.io/?text=-+list%0A-+with%0A++-+nested%0A++-+items), for example, BitBucket doesn't support two spaces. - [CommonMark tutorial](https://commonmark.org/help/tutorial/10-nestedLists.html) and [StackOverflow help](https://stackoverflow.com/editing-help#advanced-lists) state 4 spaces. - jgm [says](https://talk.commonmark.org/t/nested-ordered-lists-indented-with-2-spaces-are-broken/2064/2) about two-space indents: "I think it’s incredibly bad advice for a style guide. Many implementations don’t allow a two-space indent for a sublist (and as I’ve noted above, none allow it consistently). Gruber’s original syntax description says nothing about a two-space indent, and hints at a four-space rule, which many implementations follow. A style guide should encourage a style that will work well across implementations, and a four-space indent for sublists is the best advice for portability." The rule description even mentions the tradeoffs but I still find it a bit strange that aesthetics would be chosen over functionality. The question I wanted to ask is whether you'd make the same choice today. I personally don't mind the default too much, the main thing for me is that it is customizable (which I _always_ do), I just wanted to learn more about the context as it seems that markdownlint is used as one of the arguments for 2-spaced nested lists in the discussions mentioned above. Thanks!

kerem

2026-03-03 01:23:53 +03:00

closed this issue
added the
enhancement
label

kerem commented

2026-03-03 01:23:54 +03:00

Author

Owner

@DavidAnson commented on GitHub (Aug 11, 2018):

In no particular order:

I didn't realize this was such a controversial issue until you pointed it out!

MD007 is one of the core rules I inherited from the Ruby implementation when I created this one using Node. I had an explicit goal at the time to match behavior as closely as possible, so what's in place today is heavily derived from someone else's decision.

That said, I typically agree with Mark's original direction and probably would have implemented this rule the same on my own!

I agree that two spaces look nicer and considering that the primary goal of Markdown was to create a format that looks nice and is easy to read, this is significant.

Following your comparison link, it appears to me that 30 parsers treat 2 spaces as a nested unordered list and just 3 do not. Switching to 4 spaces changes that to 32 and 1, but that is not much different and it is still not universal agreement.

Gruber's documentation does not appear to cover the topic of nested lists, but the Dingus creates a nested unordered list from a 2 space indent.

I am not very concerned about what happens for lists of more than 100 items, and I'm not looking to convince people that my way is better.

What I'd like is for MD007 to easily allow 3- and 4-space documents for people who prefer that. As you note, that is already possible today through configuration, but it would be nice if the rule could be a little smarter by default. I will use this issue to look into adding that in a future release.

@DavidAnson commented on GitHub (Aug 11, 2018): In no particular order: I didn't realize this was such a controversial issue until you pointed it out! MD007 is one of the core rules I inherited from the [Ruby implementation](https://github.com/markdownlint/markdownlint) when I created this one using Node. I had an explicit goal at the time to match behavior as closely as possible, so what's in place today is heavily derived from someone else's decision. That said, I typically agree with Mark's original direction and probably would have implemented this rule the same on my own! I agree that two spaces look nicer and considering that the primary goal of Markdown was to create a format that looks nice and is easy to read, this is significant. Following your comparison link, it appears to me that 30 parsers treat 2 spaces as a nested unordered list and just 3 do not. Switching to 4 spaces changes that to 32 and 1, but that is not much different and it is still not universal agreement. Gruber's documentation does not appear to cover the topic of nested lists, but the [Dingus](https://daringfireball.net/projects/markdown/dingus) creates a nested unordered list from a 2 space indent. I am not very concerned about what happens for lists of more than 100 items, and I'm not looking to convince people that my way is better. What I'd like is for MD007 to easily allow 3- and 4-space documents for people who prefer that. As you note, that is already possible today through configuration, but it would be nice if the rule could be a little smarter by default. I will use this issue to look into adding that in a future release.

kerem commented

2026-03-03 01:23:54 +03:00

Author

Owner

@borekb commented on GitHub (Aug 12, 2018):

Thank you for the explanation!

@borekb commented on GitHub (Aug 12, 2018): Thank you for the explanation!

kerem commented

2026-03-03 01:23:54 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 8, 2019):

I've thought about this and don't have a good way to support 2- and 4-space-people without changing the default parameter value or asking one of them to customize. 2-people won't want to allow 4-space behavior and 4-people won't want 2-space behavior, so trying to detect from the file doesn't seem good enough for this rule. Because of that, I'm going to leave things alone for now. Thanks for raising the issue, though!

@DavidAnson commented on GitHub (Mar 8, 2019): I've thought about this and don't have a good way to support 2- and 4-space-people without changing the default parameter value or asking one of them to customize. 2-people won't want to allow 4-space behavior and 4-people won't want 2-space behavior, so trying to detect from the file doesn't seem good enough for this rule. Because of that, I'm going to leave things alone for now. Thanks for raising the issue, though!

kerem commented

2026-03-03 01:23:54 +03:00

Author

Owner

@Ark-kun commented on GitHub (Nov 4, 2025):

@DavidAnson User feedback: The markdownlint's auto-formatter just broke our MKDocs-based website. Python's Markdown library requires 4 spaces for the 2nd level of list, but markdownlint has auto-formatted it to 2 spaces, breaking the rendering.

Is there any way to configure this?

@Ark-kun commented on GitHub (Nov 4, 2025): @DavidAnson User feedback: The markdownlint's auto-formatter just broke our MKDocs-based website. Python's Markdown library requires 4 spaces for the 2nd level of list, but markdownlint has auto-formatted it to 2 spaces, breaking the rendering. Is there any way to configure this?

kerem commented

2026-03-03 01:23:54 +03:00

Author

Owner

@DavidAnson commented on GitHub (Nov 4, 2025):

MD007 is configurable: https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md

@DavidAnson commented on GitHub (Nov 4, 2025): MD007 is configurable: https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md

kerem referenced this issue

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

[GH-ISSUE #119] Include filename in mardown-it objects #1948