[GH-ISSUE #1162] MD051 support icon

kerem commented

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

Owner

Originally created by @unional on GitHub (Mar 26, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1162

[🔀 distributive](#🔀-distributive)

## 🔀 Distributive

...

Originally created by @unional on GitHub (Mar 26, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1162 ![image](https://github.com/DavidAnson/markdownlint/assets/3254987/1d1a0d4b-27b9-4510-9692-067fa4d0272d) ```md [🔀 distributive](#🔀-distributive) ## 🔀 Distributive ... ```

kerem

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

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 26, 2024):

This rule expects the GitHub representation which is described at the bottom of the documentation and does not include emoji: https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md

If that representation is used, no warning is produced: https://dlaa.me/markdownlint/#%25m%23%20%F0%9F%94%80%20Distributive%0A%0A%5B%F0%9F%94%80%20distributive%5D(%23-distributive)%0A

The rule is operating as intended.

@DavidAnson commented on GitHub (Mar 26, 2024): This rule expects the GitHub representation which is described at the bottom of the documentation and does not include emoji: https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md If that representation is used, no warning is produced: https://dlaa.me/markdownlint/#%25m%23%20%F0%9F%94%80%20Distributive%0A%0A%5B%F0%9F%94%80%20distributive%5D(%23-distributive)%0A The rule is operating as intended.

kerem commented

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

Author

Owner

@unional commented on GitHub (Mar 27, 2024):

Maybe this is an issue on vscode. The #-distributive without the emoji does not work.

@unional commented on GitHub (Mar 27, 2024): Maybe this is an issue on vscode. The `#-distributive` without the emoji does not work.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 27, 2024):

From what I can tell, GitHub web does not recognize the link in your example - whereas it does for the link that markdownlint accepts in my demo. In the interest of supporting a single canonical way of defining heading links which are not part of the CommonMark specification, GitHub seems to be the next-best authority on Markdown (see: GitHub Flavored Markdown). As such, I feel the current behavior of markdownlint is reasonable and I encourage you to open an issue in the VS Code repo for them to allow or convert to GitHub's approach.

@DavidAnson commented on GitHub (Mar 27, 2024): From what I can tell, GitHub web does not recognize the link in your example - whereas it does for the link that markdownlint accepts in my demo. In the interest of supporting a single canonical way of defining heading links which are not part of the CommonMark specification, GitHub seems to be the next-best authority on Markdown (see: GitHub Flavored Markdown). As such, I feel the current behavior of markdownlint is reasonable and I encourage you to open an issue in the VS Code repo for them to allow or convert to GitHub's approach.

kerem commented

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

Author

Owner

@giacomorebecchi commented on GitHub (Apr 4, 2024):

Hi, I stumbled upon this issue as well. I realised that mkdocs removes the leading -, hence in your case the correct link would be #distributive. Do you think there is the space to add a possibility to configure the removal of leading dashes? Thanks!

@giacomorebecchi commented on GitHub (Apr 4, 2024): Hi, I stumbled upon this issue as well. I realised that `mkdocs` removes the leading `-`, hence in your case the correct link would be `#distributive`. Do you think there is the space to add a possibility to configure the removal of leading dashes? Thanks!

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Apr 5, 2024):

@giacomorebecchi, can you link to the documentation, specification, or implementation of that mkdocs behavior?

@DavidAnson commented on GitHub (Apr 5, 2024): @giacomorebecchi, can you link to the documentation, specification, or implementation of that mkdocs behavior?

kerem commented

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

Author

Owner

@giacomorebecchi commented on GitHub (Apr 5, 2024):

@giacomorebecchi, can you link to the documentation, specification, or implementation of that mkdocs behavior?

I couldn't find an explicit reference in the documentation, but, after a bit of deep-diving, I found out that:

Anchoring links in mkdocs are calculated by the toc extension
toc calls the slugify function to transform a Heading into the correct link (see here the source code)

slugify(" My test 🐛", "-") == "my-test"
slugify("🐛 My test 🐛", "-") == "my-test"

The reason is that it calls strip before replacing whitespaces with -

@giacomorebecchi commented on GitHub (Apr 5, 2024): > @giacomorebecchi, can you link to the documentation, specification, or implementation of that mkdocs behavior? I couldn't find an explicit reference in the documentation, but, after a bit of deep-diving, I found out that: 1. Anchoring links in mkdocs are calculated by the `toc` extension 2. `toc` calls the `slugify` function to transform a Heading into the correct link (see [here](https://github.com/Python-Markdown/markdown/blob/993b57b8ea577f2120f7d0c81b45ee5ed74a0f57/markdown/extensions/toc.py#L38-L45) the source code) ```py slugify(" My test 🐛", "-") == "my-test" slugify("🐛 My test 🐛", "-") == "my-test" ``` The reason is that it calls `strip` before replacing whitespaces with `-`

kerem commented

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

Author

Owner

@unional commented on GitHub (Apr 5, 2024):

FYI you can see that the issue on vscode is closed: https://github.com/microsoft/vscode-markdown-languageservice/issues/171

Next version of vscode will have the fix.

vscode will be using https://github.com/Flet/github-slugger

@unional commented on GitHub (Apr 5, 2024): FYI you can see that the issue on vscode is closed: https://github.com/microsoft/vscode-markdown-languageservice/issues/171 Next version of vscode will have the fix. vscode will be using https://github.com/Flet/github-slugger

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Apr 5, 2024):

Thanks! It sounds like VS Code is also standardizing on GitHub behavior. That doesn't mean markdownlint can't also allow other forms, but it makes it a bit less interesting in my mind.

@DavidAnson commented on GitHub (Apr 5, 2024): Thanks! It sounds like VS Code is also standardizing on GitHub behavior. That doesn't mean markdownlint can't also allow other forms, but it makes it a bit less interesting in my mind.

kerem commented

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

Author

Owner

@giacomorebecchi commented on GitHub (Apr 5, 2024):

@DavidAnson I understand that it looks minor to you, but do you see the opportunity to accept a contribution to make this behaviour parametrisable? It would turn out to be very useful for me! If yes, I could try to work on it (although I've never written anything in JS, but that would be a nice chance to learn). Thanks in advance!

@giacomorebecchi commented on GitHub (Apr 5, 2024): @DavidAnson I understand that it looks minor to you, but do you see the opportunity to accept a contribution to make this behaviour parametrisable? It would turn out to be very useful for me! If yes, I could try to work on it (although I've never written anything in JS, but that would be a nice chance to learn). Thanks in advance!

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Apr 5, 2024):

@giacomorebecchi I'm not intimidated by the amount of work here. I am questioning whether it is a good change to add. So far, when dealing with syntax and behavior that is not part of the CommonMark specification, I have used the GitHub-Flavored Markdown specification and that has worked well. This behavior is not described there, but by matching GitHub, I feel this behavior is consistent with that spirit.

The kind of changes here do not seem to lend themselves to expressing abstractly with text or regular expression, so the customization mechanism may need to be implementing multiple behaviors in the rule and allowing people to choose among them. (Allowing both implementations together creates situations where mistakes are not detected.) That is additional complexity for me to deal with and it opens the door for people with other scenarios to want to add them as well. My impression (and I do not have data for this, so would welcome it!) is that GitHub and VS Code represent the vast majority of the use of heading links in practice, so the benefits of doing so are limited.

@DavidAnson commented on GitHub (Apr 5, 2024): @giacomorebecchi I'm not intimidated by the amount of work here. I am questioning whether it is a good change to add. So far, when dealing with syntax and behavior that is not part of the CommonMark specification, I have used the GitHub-Flavored Markdown specification and that has worked well. This behavior is not described there, but by matching GitHub, I feel this behavior is consistent with that spirit. The kind of changes here do not seem to lend themselves to expressing abstractly with text or regular expression, so the customization mechanism may need to be implementing multiple behaviors in the rule and allowing people to choose among them. (Allowing both implementations together creates situations where mistakes are not detected.) That is additional complexity for me to deal with and it opens the door for people with other scenarios to want to add them as well. My impression (and I do not have data for this, so would welcome it!) is that GitHub and VS Code represent the vast majority of the use of heading links in practice, so the benefits of doing so are limited.

kerem commented

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

Author

Owner

@giacomorebecchi commented on GitHub (Apr 9, 2024):

@DavidAnson I understand your point, thanks for the detailed explanation! I have no data regarding usage of GitHub and VSCode w.r.t. Mkdocs. I think I will proceed by making an alternative extension to toc that follows GitHub-Flavored Markdown specification. Thanks again for your work and support!

@giacomorebecchi commented on GitHub (Apr 9, 2024): @DavidAnson I understand your point, thanks for the detailed explanation! I have no data regarding usage of GitHub and VSCode w.r.t. Mkdocs. I think I will proceed by making an alternative extension to `toc` that follows GitHub-Flavored Markdown specification. Thanks again for your work and support!

Rows
Columns

[GH-ISSUE #1162] MD051 support icon #2477