[GH-ISSUE #830] MD051: Add support for custom heading anchor IDs #545

New issue

Closed

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

kerem commented

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

Owner

Originally created by @scottamain on GitHub (May 24, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/830

Many MD parsers allow for custom anchor names on headings as follows:

## Some Section {#name}

With this markup, I can change the heading but keep the anchor name the same and avoid breaking links.

The problem is that MD051 will now flag this as an invalid link:

See [some section](#name)

It would be great if markdownlint could capture {#name} as the heading ID to avoid this false positive.

(Although some MD parsers also allow you to use this syntax to add IDs on other elements, I believe headings are the most common and would be a great starting point to add this support. Then if there's demand, perhaps add support for custom IDs on other elements such as images or other arbitrary elements.)

Originally created by @scottamain on GitHub (May 24, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/830 Many MD parsers allow for custom anchor names on headings as follows: ``` ## Some Section {#name} ``` With this markup, I can change the heading but keep the anchor name the same and avoid breaking links. The problem is that MD051 will now flag this as an invalid link: ``` See [some section](#name) ``` It would be great if markdownlint could capture `{#name}` as the heading ID to avoid this false positive. (Although some MD parsers also allow you to use this syntax to add IDs on other elements, I believe headings are the most common and would be a great starting point to add this support. Then if there's demand, perhaps add support for custom IDs on other elements such as images or other arbitrary elements.)

kerem

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

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

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

Author

Owner

@lonix1 commented on GitHub (Aug 15, 2023):

This is a great update, thanks.

There are a number of related repos, so I'm unsure how they all interact... When does it land in the vscode extension?

@lonix1 commented on GitHub (Aug 15, 2023): This is a great update, thanks. There are a number of related repos, so I'm unsure how they all interact... When does it land in the vscode extension?

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Aug 15, 2023):

https://github.com/DavidAnson/markdownlint/blob/main/doc/ReleaseProcess.md

@DavidAnson commented on GitHub (Aug 15, 2023): https://github.com/DavidAnson/markdownlint/blob/main/doc/ReleaseProcess.md

kerem commented

2026-03-03 01:27:55 +03:00

Author

Owner

@lonix1 commented on GitHub (Aug 15, 2023):

@scottamain Are you using vscode? I just realised that this:

## Some Section {#name}

will be rendered verbatim - that ugly suffix is shown in the vscode preview.

So this update is good for github (I hope?) but not vscode.

@lonix1 commented on GitHub (Aug 15, 2023): @scottamain Are you using vscode? I just realised that this: ```md ## Some Section {#name} ``` will be rendered verbatim - that ugly suffix is shown in the vscode preview. So this update is good for github (I hope?) but not vscode.

kerem referenced this issue

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

[GH-ISSUE #545] MD053 should support "[//]: # (Comment)" pattern by default #2293