[GH-ISSUE #826] markdownlint lints HTML comments when proper-names is used #2390

New issue

Closed

opened 2026-03-07 20:07:20 +03:00 by kerem · 2 comments

kerem commented

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

Owner

Originally created by @axilleas on GitHub (May 23, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/826

It seems there's a bug introduced between 0.27.0 and 0.28.0.

If there's an HTML comment in a Markdown document and proper-names is used in the configuration, markdownlint lints the HTML comment. This should not be the case according to https://github.com/DavidAnson/markdownlint/blob/main/README.md#configuration

Two kinds of text are ignored:

HTML comments

Front matter

Steps to reproduce

To reproduce, use the markdownlint-cli2 library, with the following configuration:

---
proper-names:
  names: [
    "Markdownlint"
  ]

And a Markdown file:

# Test

<!-- markdownlint -->

Test with markdownlint-cli2@0.6.0 which includes markdownlint 0.27.0 , no error should be thrown:

$ yarn add markdownlint-cli2@0.6.0
$ node_modules/markdownlint-cli2/markdownlint-cli2-config.js .markdownlint.yml test.md

markdownlint-cli2-config v0.6.0 (markdownlint v0.27.0)
Finding: test.md
Linting: 1 file(s)
Summary: 0 error(s)

Test with markdownlint-cli2@0.7.0 which includes markdownlint 0.28.1 , an error is thrown:

$ yarn add markdownlint-cli2@0.7.0
$ node_modules/markdownlint-cli2/markdownlint-cli2-config.js .markdownlint.yml test.md

markdownlint-cli2-config v0.7.0 (markdownlint v0.28.1)
Finding: test.md
Linting: 1 file(s)
Summary: 1 error(s)
test.md:3:6 MD044/proper-names Proper names should have the correct capitalization [Expected: Markdownlint; Actual: markdownlint]

Originally created by @axilleas on GitHub (May 23, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/826 It seems there's a bug introduced between `0.27.0` and `0.28.0`. If there's an HTML comment in a Markdown document and [`proper-names` ](https://github.com/DavidAnson/markdownlint/blob/main/doc/md044.md)is used in the configuration, markdownlint lints the HTML comment. This should not be the case according to https://github.com/DavidAnson/markdownlint/blob/main/README.md#configuration > Two kinds of text are ignored: > > - [HTML comments](https://www.w3.org/TR/html5/syntax.html#comments) > - [Front matter](https://jekyllrb.com/docs/frontmatter/) ## Steps to reproduce To reproduce, use the `markdownlint-cli2` library, with the following configuration: ```yaml --- proper-names: names: [ "Markdownlint" ] ``` And a Markdown file: ```md # Test  ``` 1. Test with `markdownlint-cli2@0.6.0` which includes markdownlint `0.27.0` , no error should be thrown: ```shell $ yarn add markdownlint-cli2@0.6.0 $ node_modules/markdownlint-cli2/markdownlint-cli2-config.js .markdownlint.yml test.md markdownlint-cli2-config v0.6.0 (markdownlint v0.27.0) Finding: test.md Linting: 1 file(s) Summary: 0 error(s) ``` 1. Test with `markdownlint-cli2@0.7.0` which includes markdownlint `0.28.1` , an error is thrown: ```shell $ yarn add markdownlint-cli2@0.7.0 $ node_modules/markdownlint-cli2/markdownlint-cli2-config.js .markdownlint.yml test.md markdownlint-cli2-config v0.7.0 (markdownlint v0.28.1) Finding: test.md Linting: 1 file(s) Summary: 1 error(s) test.md:3:6 MD044/proper-names Proper names should have the correct capitalization [Expected: Markdownlint; Actual: markdownlint] ```

kerem

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

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (May 23, 2023):

I'm surprised I didn't have a test for this, but I think the new behavior is correct. If you want to ensure a document represents a proper name with the correct spelling, you probably want to do that everywhere in the document. Comments don't get rendered, but it would be strange to have inconsistent capitalization there, I think. As implemented today, the proper-names option can be set to false to ignore comments as you propose (and like they used to be).

Here's an example: https://dlaa.me/markdownlint/#%25m%23%20Issue%20826%0A%0AMarkdownlint%0A%0A%3C!--%20Markdownlint%20--%3E%0A%0A%3C!--%20markdownlint-configure-file%20%7B%0A%20%20%22proper-names%22%3A%20%7B%0A%20%20%20%20%22html_elements%22%3A%20false%2C%0A%20%20%20%20%22names%22%3A%20%5B%0A%20%20%20%20%20%20%22markdownlint%22%0A%20%20%20%20%5D%0A%20%20%7D%0A%7D%20--%3E%0A

PS: Before you call me out on this, I will acknowledge the same argument could be made for front matter, and I have no plans to start scanning that with any of the rules. However, that's metadata rather than part of the Markdown document, so I think it's reasonable to continue treating it separately.

@DavidAnson commented on GitHub (May 23, 2023): I'm surprised I didn't have a test for this, but I think the new behavior is correct. If you want to ensure a document represents a proper name with the correct spelling, you probably want to do that everywhere in the document. Comments don't get rendered, but it would be strange to have inconsistent capitalization there, I think. As implemented today, the `proper-names` option can be set to `false` to ignore comments as you propose (and like they used to be). Here's an example: https://dlaa.me/markdownlint/#%25m%23%20Issue%20826%0A%0AMarkdownlint%0A%0A%3C!--%20Markdownlint%20--%3E%0A%0A%3C!--%20markdownlint-configure-file%20%7B%0A%20%20%22proper-names%22%3A%20%7B%0A%20%20%20%20%22html_elements%22%3A%20false%2C%0A%20%20%20%20%22names%22%3A%20%5B%0A%20%20%20%20%20%20%22markdownlint%22%0A%20%20%20%20%5D%0A%20%20%7D%0A%7D%20--%3E%0A PS: Before you call me out on this, I will acknowledge the same argument could be made for front matter, and I have no plans to start scanning that with any of the rules. However, that's metadata rather than part of the Markdown document, so I think it's reasonable to continue treating it separately.

kerem commented

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

Author

Owner

@axilleas commented on GitHub (May 23, 2023):

Aha! So there's an "html_elements": false option! I completely missed that 🤦 I should have read the docs better. I tested and it works indeed.

Before you call me out on this

😄 I would never do that 🙂

Thanks again for the quick response! I'll go ahead and close this.

@axilleas commented on GitHub (May 23, 2023): Aha! So there's an `"html_elements": false` option! I completely missed that :facepalm: I should have read the docs better. I tested and it works indeed. > Before you call me out on this 😄 I would never do that 🙂 Thanks again for the quick response! I'll go ahead and close this.