[GH-ISSUE #1411] 🐛・[Bug] Headers detection #2524

New issue

Closed

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

kerem commented

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

Owner

Originally created by @kckmzx on GitHub (Nov 8, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1411

Hi ! First, thanks for your work, it's very useful !!

Important

I think I found a bug with the header detection.

First, here is my markdown-lint configuration:

What's the problem

When two headers have the same content, but one is followed by a comment, they are considered different. Thus, when I create a link to a header that contains a comment, the MD051 rule is triggered.

Typically, I often use a comment next to the header to indicate that it should not be displayed in the table of contents (# ...  used by the Markdown All in One extension).

How to reproduce

Example of headers that should produce the same result:

Normally, the Header Example 3 should also trigger an error.

Example with the MD051 rule

Example with this header:

This link works (in the markdown preview), but the rule MD051 is triggered.

Conversely, this one does not work (in the markdown preview) but the rule MD051 is not triggered (because the header is followed by a comment and is therefore considered different).

Originally created by @kckmzx on GitHub (Nov 8, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1411 Hi ! First, thanks for your work, it's very useful !! > [!IMPORTANT] > I think I found a bug with the **header detection**. First, here is my `markdown-lint` configuration: ![image](https://github.com/user-attachments/assets/d0e03526-16d2-4b75-9312-f97fbffa9731) ### What's the problem When two headers have the same content, but one is followed by a comment, they are considered different. Thus, when I create a link to a header that contains a comment, the `MD051` rule is triggered. Typically, I often use a comment next to the header to indicate that it should not be displayed in the table of contents (`# ... ` used by the [Markdown All in One](https://github.com/yzhang-gh/vscode-markdown) extension). ### How to reproduce #### Example of headers that should produce the same result: ![image](https://github.com/user-attachments/assets/4372470a-07e2-426b-add4-0f042f55bd75) Normally, the `Header Example 3` should also trigger an error. #### Example with the MD051 rule Example with this header: ![image](https://github.com/user-attachments/assets/34211579-aa43-4da0-ad28-bf9a4f6eb292) This link works (in the markdown preview), but the rule `MD051` is triggered. ![image](https://github.com/user-attachments/assets/d06ab414-f9f3-4c68-8027-d5e2d9e9636f) ![image](https://github.com/user-attachments/assets/37d4dc00-7a0a-4829-a916-41bbb7478dcd) Conversely, this one does not work (in the markdown preview) but the rule `MD051` is not triggered (because the header is followed by a comment and is therefore considered different). ![image](https://github.com/user-attachments/assets/1448f8af-ba20-4d8a-843f-90cd8799e82f)

kerem

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

closed this issue
added the
enhancement
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Nov 8, 2024):

I'm not sure I agree the first example is wrong, but it definitely depends on whether one considers the content of the comment as part of the heading or not. I may decide it should be ignored as you suggest, but I'll need to think about that more. Your second example does not appear to be a bug because that rule honors the GitHub implementation and the GitHub-generated link for a heading followed by a comment includes the trailing dash.

@DavidAnson commented on GitHub (Nov 8, 2024): I'm not sure I agree the first example is wrong, but it definitely depends on whether one considers the content of the comment as part of the heading or not. I may decide it should be ignored as you suggest, but I'll need to think about that more. Your second example does not appear to be a bug because that rule honors the GitHub implementation and the GitHub-generated link for a heading followed by a comment includes the trailing dash.

kerem commented

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

Author

Owner

@kckmzx commented on GitHub (Nov 15, 2024):

Okay, I understand for the second example. Maybe you can add it as a setting ?

@kckmzx commented on GitHub (Nov 15, 2024): Okay, I understand for the second example. Maybe you can add it as a setting ?