starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 09:16:02 +03:00

[GH-ISSUE #1888] Question: Mixed list items not being flagged as required #2619

New issue

Closed

opened 2026-03-07 20:09:25 +03:00 by kerem · 5 comments

kerem commented

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

Owner

Originally created by @ashishguptaiitb on GitHub (Dec 11, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1888

I'm making the following formatting mistake (lack of indentation) that results in the following output from the MkDocs build engine. I want to use a linting method that prevents me from making this formatting mistake. What linting rule combination will help me prevent such a mistake -- flag mixed list items with or without a blank line, if the lists are at the same level. If the mixed lists are indented, then that's allowed and shouldn't be flagged

My unfortunate limitation is that I don't want to switch on too many list items rules. My docset has many linting issues that can't be fixed right away. And switching too many rules to true will start reporting all these as problems. It'll be too much noise in the VSCode report.

I want to highlight only the above issue. Possible?

Originally created by @ashishguptaiitb on GitHub (Dec 11, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1888 I'm making the following formatting mistake (lack of indentation) that results in the following output from the MkDocs build engine. I want to use a linting method that prevents me from making this formatting mistake. What linting rule combination will help me prevent such a mistake -- flag mixed list items with or without a blank line, if the lists are at the same level. If the mixed lists are indented, then that's allowed and shouldn't be flagged <img width="542" height="284" alt="Image" src="https://github.com/user-attachments/assets/523c76d4-45d9-4057-a380-79c06d6c1165" /> My unfortunate limitation is that I don't want to switch on too many list items rules. My docset has many linting issues that can't be fixed right away. And switching too many rules to `true` will start reporting all these as problems. It'll be too much noise in the VSCode report. I want to highlight only the above issue. Possible?

kerem

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

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Dec 11, 2025):

It sounds like you want to flag any time two top-level lists (necessarily of different kinds, I think) appear consecutively. That's not particularly complicated to author, but is not a rule that exists today.

@DavidAnson commented on GitHub (Dec 11, 2025): It sounds like you want to flag any time two top-level lists (necessarily of different kinds, I think) appear consecutively. That's not particularly complicated to author, but is not a rule that exists today.

kerem commented

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

Author

Owner

@ashishguptaiitb commented on GitHub (Dec 11, 2025):

Right, @DavidAnson . This is exactly the check I want. I am hoping that there's a combination of the existing rules that I can use to achieve it. Just want to draw my writing team's attention to such formatting, so that honest mistakes can be avoided. Is there such a combo?

Also, should it even be flagged as an issue? Do CommonMark and GFM specs permit such formatting as valid?

PS: CommonMark dingus provides an output; just that the lack of indentation leads to a lack of nesting in the output. See screenshot here https://github.com/mkdocs/mkdocs/issues/4067.

@ashishguptaiitb commented on GitHub (Dec 11, 2025): Right, @DavidAnson . This is exactly the check I want. I am hoping that there's a combination of the existing rules that I can use to achieve it. Just want to draw my writing team's attention to such formatting, so that honest mistakes can be avoided. Is there such a combo? Also, should it even be flagged as an issue? Do CommonMark and GFM specs permit such formatting as valid? --- PS: CommonMark dingus provides an output; just that the lack of indentation leads to a lack of nesting in the output. See screenshot here https://github.com/mkdocs/mkdocs/issues/4067.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Dec 11, 2025):

It is valid to have a list of one type followed by a list of another type. The output you show from CommonMark of rendering them as separate lists makes sense to me and the output you show from MkDocs of combining them seems wrong to me. I'm not seeing a way to detect this with the current set of rules, but you may find a custom rule that can do this or you might author one yourself.

https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md

@DavidAnson commented on GitHub (Dec 11, 2025): It is valid to have a list of one type followed by a list of another type. The output you show from CommonMark of rendering them as separate lists makes sense to me and the output you show from MkDocs of combining them seems wrong to me. I'm not seeing a way to detect this with the current set of rules, but you may find a custom rule that can do this or you might author one yourself. https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Dec 11, 2025):

In general, I would always place some text between two such lists to separate them, but there may be scenarios where the lists are obviously different and that's not necessary, so I would worry about false positives from introducing a rule like this to the ecosystem.

@DavidAnson commented on GitHub (Dec 11, 2025): In general, I would always place some text between two such lists to separate them, but there may be scenarios where the lists are obviously different and that's not necessary, so I would worry about false positives from introducing a rule like this to the ecosystem.

kerem commented

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

Author

Owner

@ashishguptaiitb commented on GitHub (Dec 11, 2025):

I agree wholeheartedly, monsieur :-)
Let's close this issue out. I'll call it an education and a call for diligence by us writers. You can call it yet another issue closed ;-)

Jokes aside, I really appreciate your insights + the simplification of the issue. Thank you, sir.

@ashishguptaiitb commented on GitHub (Dec 11, 2025): I agree wholeheartedly, monsieur :-) Let's close this issue out. I'll call it an education and a call for diligence by us writers. You can call it yet another issue closed ;-) Jokes aside, I really appreciate your insights + the simplification of the issue. Thank you, sir.