starred/markdownlint

Fork 0

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

[GH-ISSUE #167] Modify MD029 to allow lists starting larger than one #144

New issue

Closed

opened 2026-03-03 01:24:06 +03:00 by kerem · 4 comments

kerem commented

2026-03-03 01:24:06 +03:00

Owner

Originally created by @vstrien on GitHub (Feb 22, 2019).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/167

Currently, MD029 only considers lists starting at 1 as valid.

1. This is
2. A one-ordered
3. Valid list

However, in documentation a series of steps is often outlined with explanations in between. For example:

1. Do the first step

As you can see, the first step results in `XXX`. Now, in order to do something else later on, we need to do step 2. This paragraph is the explanation about step 2.

2. Do the first step
3. Step 3 as well..

Currently, MD029 marks the second sequence (starting at 2) as [Expected: 1; Actual: 2; Style: 1/1/1], while the "broken list" (or any list starting at another digit than just 1) displays correctly in markdown-it as well as GFM.

Originally created by @vstrien on GitHub (Feb 22, 2019). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/167 Currently, MD029 only considers lists starting at 1 as valid. ``` 1. This is 2. A one-ordered 3. Valid list ``` However, in documentation a series of steps is often outlined with explanations in between. For example: ``` 1. Do the first step As you can see, the first step results in `XXX`. Now, in order to do something else later on, we need to do step 2. This paragraph is the explanation about step 2. 2. Do the first step 3. Step 3 as well.. ``` Currently, MD029 marks the second sequence (starting at 2) as `[Expected: 1; Actual: 2; Style: 1/1/1]`, while the "broken list" (or any list starting at another digit than just 1) displays correctly in [markdown-it](https://markdown-it.github.io/#md3=%7B%22source%22%3A%221.%20Do%20the%20first%20step%5Cn%5CnAs%20you%20can%20see%2C%20the%20first%20step%20results%20in%20%60XXX%60.%20Now%2C%20in%20order%20to%20do%20something%20else%20later%20on%2C%20we%20need%20to%20do%20step%202.%20This%20paragraph%20is%20the%20explanation%20about%20step%202.%5Cn%5Cn2.%20Do%20the%20first%20step%5Cn3.%20Step%203%20as%20well..%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Atrue%2C%22_view%22%3A%22html%22%7D%7D) as well as GFM.

kerem

2026-03-03 01:24:06 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:24:07 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 22, 2019):

The example above where a paragraph is placed "inside" a list is definitely valid and I understand the scenario where it is useful. However, the linter can't tell the difference between that scenario and the (more common) scenario where the 2-item list after the paragraph is meant to be a separate list (and starts at the wrong number).

If we tried to allow this behavior, what are the rules for content that is allowed to interrupt a list? Is it just one paragraph, or two, or ten? What about another list? I'm not seeing a clear policy that will allow the tool to detect the common mis-numbering scenario AND allow the pattern above AND still remain useful.

As such, I think that disabling MD029 for this part of your project may be the most practical solution.

@DavidAnson commented on GitHub (Feb 22, 2019): The example above where a paragraph is placed "inside" a list is definitely valid and I understand the scenario where it is useful. However, the linter can't tell the difference between that scenario and the (more common) scenario where the 2-item list after the paragraph is meant to be a separate list (and starts at the wrong number). If we tried to allow this behavior, what are the rules for content that is allowed to interrupt a list? Is it just one paragraph, or two, or ten? What about another list? I'm not seeing a clear policy that will allow the tool to detect the common mis-numbering scenario AND allow the pattern above AND still remain useful. As such, I think that disabling MD029 for this part of your project may be the most practical solution.

kerem commented

2026-03-03 01:24:07 +03:00

Author

Owner

@vstrien commented on GitHub (Feb 25, 2019):

Sure, I agree. An alternative is to allow lists starting not only at one, but also at two. The cases for lists starting at 2 are almost always corner-cases though, so maybe it's easier / better to disable this single rule for those projects.

@vstrien commented on GitHub (Feb 25, 2019): Sure, I agree. An alternative is to allow lists starting not only at one, but also at two. The cases for lists starting at 2 are almost always corner-cases though, so maybe it's easier / better to disable this single rule for those projects.

kerem commented

2026-03-03 01:24:07 +03:00

Author

Owner

@redactedscribe commented on GitHub (Jul 15, 2023):

@DavidAnson I understand the difficulty with implementing a reliable rule, but I don't think disabling the rule should be the solution either. The example scenario above isn't too uncommon across projects. In my case:

1. Copy.
2. Paste.

> Warning!

3. Run thing.
4. I did a computer!

Indenting the warning doesn't make sense for it to be part of step 2.

Can we not just treat the lists as two separate lists and allow them to begin at any number? Or does that also run into issues?

VS Code's Markdown preview however doesn't seem to struggle in this scenario and renders it as a single list (at least visually) and without any of the large gaps between each list item when a list contains an empty line. Perhaps it's actually starting a new list at 3..

Thanks.

markdownlint 0.51.0
VSCodium 1.80.1

@redactedscribe commented on GitHub (Jul 15, 2023): @DavidAnson I understand the difficulty with implementing a reliable rule, but I don't think disabling the rule should be the solution either. The example scenario above isn't too uncommon across projects. In my case: ```markdown 1. Copy. 2. Paste. > Warning! 3. Run thing. 4. I did a computer! ``` Indenting the warning doesn't make sense for it to be part of step 2. Can we not just treat the lists as two separate lists and allow them to begin at any number? Or does that also run into issues? VS Code's Markdown preview however doesn't seem to struggle in this scenario and renders it as a single list (at least visually) and without any of the large gaps between each list item when a list contains an empty line. Perhaps it's actually starting a new list at `3.`. Thanks. markdownlint 0.51.0 VSCod*ium* 1.80.1

kerem commented

2026-03-03 01:24:07 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 15, 2023):

@redactedscribe, the problem is not one of detecting there is a second list, but rather of guessing whether the author wanted the two lists to seem like the same list (and have continuous numbering) or treat them as separate lists according to the specification (meaning each should start at 1). The syntax in your example defines two different lists according to the CommonMark specification and so the warning from markdownlint is correct. My suggestion for a scenario like this is to indent the warning so it is part of the second list item. As you can see below, that means there is only a single list defined and there are no warnings from markdownlint.

https://dlaa.me/markdownlint/#%25m%23%20Issue%20167%0A%0A1.%20Copy.%0A2.%20Paste.%0A%0A%20%20%20%3E%20Warning!%0A%0A3.%20Run%20thing.%0A4.%20I%20did%20a%20computer!%0A

@DavidAnson commented on GitHub (Jul 15, 2023): @redactedscribe, the problem is not one of detecting there is a second list, but rather of guessing whether the author wanted the two lists to seem like the same list (and have continuous numbering) or treat them as separate lists according to the specification (meaning each should start at 1). The syntax in your example defines two different lists according to the CommonMark specification and so the warning from markdownlint is correct. My suggestion for a scenario like this is to indent the warning so it is part of the second list item. As you can see below, that means there is only a single list defined and there are no warnings from markdownlint. <https://dlaa.me/markdownlint/#%25m%23%20Issue%20167%0A%0A1.%20Copy.%0A2.%20Paste.%0A%0A%20%20%20%3E%20Warning!%0A%0A3.%20Run%20thing.%0A4.%20I%20did%20a%20computer!%0A>

kerem referenced this issue

2026-03-03 01:24:28 +03:00

[GH-ISSUE #213] Proposal: Detect names in inline-links #183

kerem referenced this issue

2026-03-03 01:24:38 +03:00

[GH-ISSUE #232] HTML checking in MD docs #200

kerem referenced this issue

2026-03-03 01:26:22 +03:00

[GH-ISSUE #456] Add lint for a link reference without a corresponding link definition (or vice versa) #378

kerem referenced this issue

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

[GH-ISSUE #144] New rule suggestion: detect link that point to nothing #1969