starred/markdownlint

Fork 0

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

[GH-ISSUE #1959] `MD051` false positive: Link fragments for headings containing colons (`:`) are flagged as invalid #791

New issue

Closed

opened 2026-03-03 01:29:53 +03:00 by kerem · 3 comments

kerem commented

2026-03-03 01:29:53 +03:00

Owner

Originally created by @zts2005 on GitHub (Feb 15, 2026).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1959

What did you do?
I created a Markdown document with a heading containing an English colon (:) and tried to link to it using a fragment generated by removing the punctuation, which follows the GitHub heading algorithm.

Example code:

## some:thing

[link](#something)

What did you expect to happen?
The link [link](#something) should be considered valid. According to the GitHub heading algorithm (and how VS Code's built-in preview/autocomplete works), punctuation like colons should be removed when generating the fragment. Therefore, ## some:thing should result in the ID something.

What actually happened?
The linter triggers a MD051/link-fragments violation: "Link fragments should be valid".
Interestingly, if I change the colon to a Chinese colon (：) or remove it entirely, the warning disappears.

What messages or errors were there?
MD051/link-fragments: Link fragments should be valid

How can the issue be reproduced?
Paste the following content into a Markdown file with MD051 enabled:

## some:thing

[link](#something)

The linter will flag #something as invalid.

What version were you using?

VS Code markdownlint extension version: 0.61.1

What operating system were you using?
Windows 10 22H2

Originally created by @zts2005 on GitHub (Feb 15, 2026). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1959  **What did you do?** I created a Markdown document with a heading containing an English colon (`:`) and tried to link to it using a fragment generated by removing the punctuation, which follows the GitHub heading algorithm. Example code: ```markdown ## some:thing [link](#something) ``` **What did you expect to happen?** The link `[link](#something)` should be considered valid. According to the GitHub heading algorithm (and how VS Code's built-in preview/autocomplete works), punctuation like colons should be removed when generating the fragment. Therefore, `## some:thing` should result in the ID `something`. **What actually happened?** The linter triggers a `MD051/link-fragments` violation: "Link fragments should be valid". Interestingly, if I change the colon to a Chinese colon (`：`) or remove it entirely, the warning disappears. **What messages or errors were there?** `MD051/link-fragments: Link fragments should be valid` **How can the issue be reproduced?** Paste the following content into a Markdown file with `MD051` enabled: ```markdown ## some:thing [link](#something) ``` The linter will flag `#something` as invalid. **What version were you using?** * VS Code `markdownlint` extension version: 0.61.1 **What operating system were you using?** Windows 10 22H2

kerem

2026-03-03 01:29:53 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:29:54 +03:00

Author

Owner

@zts2005 commented on GitHub (Feb 15, 2026):

Oh, I think I should have submitted the issue in the main repository, but it seems I made a mistake.

I'm very sorry.

@zts2005 commented on GitHub (Feb 15, 2026): Oh, I think I should have submitted the issue in the main repository, but it seems I made a mistake. I'm very sorry.

kerem commented

2026-03-03 01:29:54 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 15, 2026):

You can see from the rendered output in the demo app that the text after the colon in your scenario is being recognized as a directive which is what causes this problem. You can read more about directives here:

https://github.com/micromark/micromark-extension-directive

This problem can be avoided by escaping the colon in the title with a backlash character as shown here:

https://dlaa.me/markdownlint/#%25m%23%20Issue%201959%0A%0A%23%23%20some%3Athing%0A%0A%5Btest%20link%5D(%23something)%0A%0A%23%23%20other%5C%3Athing%0A%0A%5Btest%20link%5D(%23otherthing)%0A

@DavidAnson commented on GitHub (Feb 15, 2026): You can see from the rendered output in the demo app that the text after the colon in your scenario is being recognized as a directive which is what causes this problem. You can read more about directives here: https://github.com/micromark/micromark-extension-directive This problem can be avoided by escaping the colon in the title with a backlash character as shown here: https://dlaa.me/markdownlint/#%25m%23%20Issue%201959%0A%0A%23%23%20some%3Athing%0A%0A%5Btest%20link%5D(%23something)%0A%0A%23%23%20other%5C%3Athing%0A%0A%5Btest%20link%5D(%23otherthing)%0A

kerem commented

2026-03-03 01:29:54 +03:00

Author

Owner

@zts2005 commented on GitHub (Feb 16, 2026):

Okay, I understand. This is the first time I have learned about this feature. Thank you.

@zts2005 commented on GitHub (Feb 16, 2026): Okay, I understand. This is the first time I have learned about this feature. Thank you.

kerem referenced this issue

2026-03-03 02:01:31 +03:00

[PR #791] [MERGED] Bump eslint from 8.38.0 to 8.39.0 #1016

kerem referenced this issue

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

[PR #791] [MERGED] Bump eslint from 8.38.0 to 8.39.0 #2866