[GH-ISSUE #1016] MD051 false positives for section titles with image in them #593

New issue

Closed

opened 2026-03-03 01:28:18 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 01:28:18 +03:00

Owner

Originally created by @JakubFranek on GitHub (Oct 22, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1016

Hello,

I am creating a glossary-like Markdown file for my project. I add relevant icons to some of the section titles like this:

## Buy ![Icon](../resources/icons/buy.png)

Buy is a sub-type of [Security Transaction](#security-transaction) that represents...

Turns out the correct way to link to these section titles is to include the word "icon" from the image link within the section link [like this](#buy-icon)

The linking works perfectly fine like this, however, markdownlint reports false positive MD051 warnings:

I tried putting empty string in the image link square brackets, and although it caused the correct section link to be [like this](#buy) (i.e. without the word "icon"), the warnings persisted. It seems to me markdownlint is somehow confused by section titles with image links in them.

Is there a way to link to section titles with icons without causing MD051 warnings? Thanks a lot for any help.

Regards
Jakub

Originally created by @JakubFranek on GitHub (Oct 22, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1016 Hello, I am creating a glossary-like Markdown file for my project. I add relevant icons to some of the section titles like this: ``` ## Buy ![Icon](../resources/icons/buy.png) Buy is a sub-type of [Security Transaction](#security-transaction) that represents... ``` ![buy-section](https://github.com/DavidAnson/markdownlint/assets/33395319/c2755e35-ba2b-40eb-991d-c2ea753bf40a) Turns out the correct way to link to these section titles is to include the word "icon" from the image link within the section link `[like this](#buy-icon)` The linking works perfectly fine like this, however, markdownlint reports false positive MD051 warnings: ![false positive MD051](https://github.com/DavidAnson/markdownlint/assets/33395319/7af8086f-779f-402b-99a0-df9ad87f5565) I tried putting empty string in the image link square brackets, and although it caused the correct section link to be `[like this](#buy)` (i.e. without the word "icon"), the warnings persisted. It seems to me markdownlint is somehow confused by section titles with image links in them. Is there a way to link to section titles with icons without causing MD051 warnings? Thanks a lot for any help. Regards Jakub

kerem

2026-03-03 01:28:18 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:28:19 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 22, 2023):

GitHub creates the following anchor for your original example: #buy-. Using that syntax does not produce a warning from markdownlint: https://dlaa.me/markdownlint/#%25m%23%20Issue%201016%0A%0A%23%23%20Buy%20!%5BIcon%5D(..%2Fresources%2Ficons%2Fbuy.png)%0A%0A%5BLink%5D(%23buy-)%0A

You can read more about this rule's support for the GitHub algorithm toward the bottom of this documentation page: https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md

It seems like you are using some other platform/algorithm which includes the image description in automatically created anchor links. You may be able to create a named anchor or use an HTML anchor tag to create a custom name and reference that instead. The documentation above includes examples of both.

@DavidAnson commented on GitHub (Oct 22, 2023): GitHub creates the following anchor for your original example: `#buy-`. Using that syntax does not produce a warning from markdownlint: https://dlaa.me/markdownlint/#%25m%23%20Issue%201016%0A%0A%23%23%20Buy%20!%5BIcon%5D(..%2Fresources%2Ficons%2Fbuy.png)%0A%0A%5BLink%5D(%23buy-)%0A You can read more about this rule's support for the GitHub algorithm toward the bottom of this documentation page: https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md It seems like you are using some other platform/algorithm which includes the image description in automatically created anchor links. You may be able to create a named anchor or use an HTML anchor tag to create a custom name and reference that instead. The documentation above includes examples of both.

kerem commented

2026-03-03 01:28:19 +03:00

Author

Owner

@JakubFranek commented on GitHub (Oct 22, 2023):

Thanks a lot, you are absolutely correct. The links were working when I used the VS Code native Markdown preview, which put me on the wrong track, but on GitHub they obey different rules. markdownlint works fine with GitHub style links which is good enough for me since GitHub is the intended target of my Markdowns. Thanks again.

@JakubFranek commented on GitHub (Oct 22, 2023): Thanks a lot, you are absolutely correct. The links were working when I used the VS Code native Markdown preview, which put me on the wrong track, but on GitHub they obey different rules. markdownlint works fine with GitHub style links which is good enough for me since GitHub is the intended target of my Markdowns. Thanks again.

kerem referenced this issue

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

[GH-ISSUE #593] Docs: document how to extend from a built-in style #2314