[GH-ISSUE #1618] Proposed rules for markdown comment formatting and readability. #2569

New issue

Open

opened 2026-03-07 20:08:59 +03:00 by kerem · 0 comments

kerem commented

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

Owner

Originally created by @wwarriner on GitHub (May 29, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1618

I'd like to propose one or more new rules around the use of HTML comments.

No non-comment content on the same line as a comment open or close if the comment is multi-line.
No comment content on the same line as a comment open or close, except for single-line comment. Could be split into open, close, both options.
Exactly one space before and after comment content in single-line comments.
No non-comment content on the same line as a single-line comment.

The following would trigger (1):

md <!--
comment
-->

<!--
comment
--> md

The following would trigger (2):

<!-- comment
-->

<!--
comment -->

The following would trigger (3):

<!--comment -->
<!-- comment-->
<!--  comment -->
<!-- comment  -->

The following would trigger (4):

md <!-- comment -->
<!-- comment --> md

I understand (4) may be the most contentious. The first three proposals are in line with linters, formatters, and parsers for other languages, and improve readability.

None of these should change page rendering, at least in MkDocs. All of them should be automatically fixable as well. Multiline comments would stay multiline comments, single line comments would stay single line comments, markdown content would be pushed to the appropriate locations away from the comments, and spaces in single line comments would be standardized.

I assume this would also apply to comments which are markdownlint-* directives. There is an open question of how to disable this/these rules, which might involve comments around comments. I don't think that would break anything, nor why someone would want to do that.

Originally created by @wwarriner on GitHub (May 29, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1618  I'd like to propose one or more new rules around the use of HTML comments. 1. No non-comment content on the same line as a comment open or close if the comment is multi-line. 2. No comment content on the same line as a comment open or close, except for single-line comment. Could be split into open, close, both options. 3. Exactly one space before and after comment content in single-line comments. 4. No non-comment content on the same line as a single-line comment. The following would trigger (1): ``` md   md ``` The following would trigger (2): ```   ``` The following would trigger (3): ```     ``` The following would trigger (4): ``` md   md ``` I understand (4) may be the most contentious. The first three proposals are in line with linters, formatters, and parsers for other languages, and improve readability. None of these should change page rendering, at least in MkDocs. All of them should be automatically fixable as well. Multiline comments would stay multiline comments, single line comments would stay single line comments, markdown content would be pushed to the appropriate locations away from the comments, and spaces in single line comments would be standardized. I assume this would also apply to comments which are `markdownlint-*` directives. There is an open question of how to disable this/these rules, which might involve comments around comments. I don't think that would break anything, nor why someone would want to do that.