MD051 support icon

[unional]

MD051 support icon

[DavidAnson]

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.

[unional]

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

[DavidAnson]

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.

[giacomorebecchi]

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!

[DavidAnson]

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

[giacomorebecchi]

@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 the source code)

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

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

[unional]

FYI you can see that the issue on vscode is closed: microsoft/vscode-markdown-languageservice#171

Next version of vscode will have the fix.

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

[DavidAnson]

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.

[giacomorebecchi]

@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!

[DavidAnson]

@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.

[giacomorebecchi]

@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!