starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-26 01:36:03 +03:00

[GH-ISSUE #431] Comments in Lists #2208

New issue

Closed

opened 2026-03-07 20:05:32 +03:00 by kerem · 8 comments

kerem commented

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

Owner

Originally created by @Foggalong on GitHub (Sep 22, 2021).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/431

MD032 is being flagged when HTML comments are included between list items. General example is

- item <!-- comment -->
- item <!-- comment -->
<!--
  - commented subitem: description
  - commented subitem: description
-->
- item <!-- comment -->
- item <!-- comment -->

Markdown lint is complaining that lines 2 and 7 are MD032 violations because there aren't spaces around them, but if spaces are added (between 2 & 3 and 6 & 7) then that separates the sublist from the list and, when uncommented, leads to MD012 being flagged.

Alternatively, the comment can be adjusted so that it looks like

- item <!-- comment -->
- item <!-- comment -->
<!--- commented subitem: description
    - commented subitem: description-->
- item <!-- comment -->
- item <!-- comment -->

but (as well as looking weird) that flags a MD007 error when the sublist is uncommented.

From what I can tell there isn't a way to structure comments in lists without breaking one of those three rules. The ideal fix (I think) would be for MD032 to not fail in cases where the non-empty line next to the list is a comment, as a bonus going on to check if the line the other side of the comment is a list item or a blank line.

The context for this issue was this GitHub issue template which has a commented sublist and so seemingly can never be markdownlint compliant.

Originally created by @Foggalong on GitHub (Sep 22, 2021). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/431 MD032 is being flagged when HTML comments are included between list items. General example is ```markdown - item  - item   - item  - item  ``` Markdown lint is complaining that lines 2 and 7 are MD032 violations because there aren't spaces around them, but if spaces are added (between 2 & 3 and 6 & 7) then that separates the sublist from the list and, when uncommented, leads to MD012 being flagged. Alternatively, the comment can be adjusted so that it looks like ```markdown - item  - item   - item  - item  ``` but (as well as looking weird) that flags a MD007 error when the sublist is uncommented. From what I can tell there isn't a way to structure comments in lists without breaking one of those three rules. The ideal fix (I think) would be for MD032 to not fail in cases where the non-empty line next to the list is a comment, as a bonus going on to check if the line the other side of the comment is a list item or a blank line. The context for this issue was [this GitHub issue template](https://github.com/jdm-contrib/jdm/blob/master/.github/ISSUE_TEMPLATE/new_entry.md) which has a [commented sublist](https://raw.githubusercontent.com/jdm-contrib/jdm/master/.github/ISSUE_TEMPLATE/new_entry.md) and so seemingly can never be markdownlint compliant.

kerem

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

closed this issue
added the
bug

fixed in next
labels

kerem commented

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

Author

Owner

@Foggalong commented on GitHub (Sep 22, 2021):

Also flagged this at markdownlint/markdownlint#390 since (I think?) this project operates separately but let me know if I've misunderstood that 🙂

@Foggalong commented on GitHub (Sep 22, 2021): Also flagged this at markdownlint/markdownlint#390 since (I think?) this project operates separately but let me know if I've misunderstood that :slightly_smiling_face:

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 22, 2021):

The violation is correct, the original sample creates two lists according to the CommonMark specification (the first has no blanks after and the second has no blanks before): https://markdown-it.github.io/#md3=%7B%22source%22%3A%22-%20item%20%3C!--%20comment%20--%3E%5Cn-%20item%20%3C!--%20comment%20--%3E%5Cn%3C!--%5Cn%20%20-%20commented%20subitem%3A%20description%5Cn%20%20-%20commented%20subitem%3A%20description%5Cn--%3E%5Cn-%20item%20%3C!--%20comment%20--%3E%5Cn-%20item%20%3C!--%20comment%20--%3E%22%2C%22defaults%22%3A%7B%22html%22%3Atrue%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%3Afalse%2C%22_view%22%3A%22src%22%7D%7D

@DavidAnson commented on GitHub (Sep 22, 2021): The violation is correct, the original sample creates two lists according to the CommonMark specification (the first has no blanks after and the second has no blanks before): https://markdown-it.github.io/#md3=%7B%22source%22%3A%22-%20item%20%3C!--%20comment%20--%3E%5Cn-%20item%20%3C!--%20comment%20--%3E%5Cn%3C!--%5Cn%20%20-%20commented%20subitem%3A%20description%5Cn%20%20-%20commented%20subitem%3A%20description%5Cn--%3E%5Cn-%20item%20%3C!--%20comment%20--%3E%5Cn-%20item%20%3C!--%20comment%20--%3E%22%2C%22defaults%22%3A%7B%22html%22%3Atrue%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%3Afalse%2C%22_view%22%3A%22src%22%7D%7D

kerem commented

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

Author

Owner

@Foggalong commented on GitHub (Sep 22, 2021):

This example is also creates two lists according to the CommonMark specification but doesn't get flagged as a markdown lint violation.

- item <!-- comment -->
<!--  - subitem -->
- item <!-- comment -->

It's specifically multi-line comments inside lists that are being misflagged.

@Foggalong commented on GitHub (Sep 22, 2021): This example is also creates two lists according to the CommonMark specification but _doesn't_ get flagged as a markdown lint violation. ```markdown - item   - item  ``` It's specifically multi-line comments inside lists that are being misflagged.

kerem commented

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

Author

Owner

@Foggalong commented on GitHub (Sep 22, 2021):

Similarly fine is

- item <!-- comment -->
- item <!-- comment -->
<!--  - commented subitem: description -->
<!--  - commented subitem: description -->
- item <!-- comment -->
- item <!-- comment -->

but it's more of a workaround than a fix to the actual multiline comment issue.

@Foggalong commented on GitHub (Sep 22, 2021): Similarly fine is ```markdown - item  - item    - item  - item  ``` but it's more of a workaround than a fix to the actual multiline comment issue.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 22, 2021):

The single-line comment not generating a warning looks like a bug. I'll have a look, here's the repro: https://dlaa.me/markdownlint/#%25m%23%20Issue%20431%0A%0A-%20item%20%3C!--%20comment%20--%3E%0A%3C!--%20%20-%20subitem%20--%3E%0A-%20item%20%3C!--%20comment%20--%3E%0A

@DavidAnson commented on GitHub (Sep 22, 2021): The single-line comment not generating a warning looks like a bug. I'll have a look, here's the repro: https://dlaa.me/markdownlint/#%25m%23%20Issue%20431%0A%0A-%20item%20%3C!--%20comment%20--%3E%0A%3C!--%20%20-%20subitem%20--%3E%0A-%20item%20%3C!--%20comment%20--%3E%0A

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 22, 2021):

I think your last example there looks like a good compromise - but it may start generating violations in a future release. :)

@DavidAnson commented on GitHub (Sep 22, 2021): I think your last example there looks like a good compromise - but it may start generating violations in a future release. :)

kerem commented

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

Author

Owner

@Foggalong commented on GitHub (Sep 23, 2021):

Haha, seems I've found a bug but not the bug I thought I'd found!

@Foggalong commented on GitHub (Sep 23, 2021): Haha, seems I've found a bug but not the bug I thought I'd found!

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Dec 20, 2021):

When I looked at the code, I decided the tool's definition of "blank line" should have treated all your examples as scenarios that did NOT generate MD032. The next release of the library should behave as you expected. Here's the new test case: https://raw.githubusercontent.com/DavidAnson/markdownlint/6dea67825aac29bc6e43bd932d641e2bfe7b38ff/test/lists-with-commented-items.md

@DavidAnson commented on GitHub (Dec 20, 2021): When I looked at the code, I decided the tool's definition of "blank line" should have treated all your examples as scenarios that did NOT generate MD032. The next release of the library should behave as you expected. Here's the new test case: https://raw.githubusercontent.com/DavidAnson/markdownlint/6dea67825aac29bc6e43bd932d641e2bfe7b38ff/test/lists-with-commented-items.md