[GH-ISSUE #1308] [Proposal] Rule to disallow links in headings #658

New issue

Closed

opened 2026-03-03 01:28:50 +03:00 by kerem · 3 comments

kerem commented

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

Owner

Originally created by @Arty-chan on GitHub (Jul 26, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1308

A lot of markdown renderers on sites auto-create anchor links to headings.

While if there is a link in a heading, the anchor will still work, clicking on the heading can lead you to the specified link instead of giving you the anchor link. This disrupts the default behaviour of the heading.

It's particularly problematic in something that is generated off the headings. For example, if you have a table of contents generated from the headings, many generators will not strip out the link, so when you click on the heading in the table of contents, it goes to the specified link instead of to the heading on the current page.

I'm creating a custom rule in another linter (vale) so it's not a priority for me, but thought this would be a good idea to include as a rule in markdownlint.

Originally created by @Arty-chan on GitHub (Jul 26, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1308 A lot of markdown renderers on sites auto-create anchor links to headings. While if there is a link in a heading, the anchor will still work, clicking on the heading can lead you to the specified link instead of giving you the anchor link. This disrupts the default behaviour of the heading. It's particularly problematic in something that is generated off the headings. For example, if you have a table of contents generated from the headings, many generators will not strip out the link, so when you click on the heading in the table of contents, it goes to the specified link instead of to the heading on the current page. I'm creating a custom rule in another linter (vale) so it's not a priority for me, but thought this would be a good idea to include as a rule in markdownlint.

kerem

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

closed this issue
added the
new rule
label

kerem commented

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

Author

Owner

@berot3 commented on GitHub (May 19, 2025):

I think it would be nice to have the option to disallow links in headings. but i als agree with the discussion here #762

@berot3 commented on GitHub (May 19, 2025): I think it would be nice to have the option to disallow links in headings. but i als agree with the discussion here #762

kerem commented

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

Author

Owner

@Malix-Labs commented on GitHub (Jul 14, 2025):

Duplicate of #762

@Malix-Labs commented on GitHub (Jul 14, 2025): Duplicate of #762

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Jul 14, 2025):