New Rule: link-fragments-should-be-valid

[SwetaTanwar]

Rule details

This rule should warn when a link fragment does not match any of the fragments that are automatically generated for headings in a document

What type of rule is this?

Warns about a potential problem

Example code

Incorrect Code

# Heading Name

[Link](#fragment)

Correct Code

# Heading Name

[Link](#heading-name)

Participation

• I am willing to submit a pull request to implement this rule.

Additional comments

Prior At: Rule

[snitin315]

I'm 👍🏻 for this rule & I feel this should also be recommended.

[snitin315]

I think this was also discussed & accepted previously in #319 (comment)

For the rule name, we can call it no-missing-link-fragments

[Pixel998]

I think this is a good idea. @SwetaTanwar Are you planning to submit a PR for this? If not, I can take it on.

[lumirlumir]

Yes, I agree that this rule is worth implementing.

However, I’m concerned that it has some tricky aspects.

Some Markdown parsers handle heading link fragments in their own ways. For example, one parser might convert Heading with .dot to heading-with-dot, while another might interpret it as heading-with-.dot. This might not be the exact case, but I’ve seen many websites generate link fragments differently.

The behavior of markdownlint's rule can be one possible approach, as it internally uses the GitHub Heading Algorithm.

However, if our goal is to mimic what markdownlint does, this approach shouldn't be recommended, as it doesn't handle all general cases well.

Personally, I always use markdownlint internally for all my projects, but I disable this specific rule because there are so many cases it fails to handle properly.

Additionally, in general usage, we need to consider that many Markdown parsers support custom link fragments like this:

# Heading 1 {#custom-heading-1-it-is-possible-for-many-markdown-parsers}

This is commonly used syntax, supported by popular parsers like markdown-it and remark.

---

So in conclusion, it would be great to implement and recommend this rule if we can account for these cases properly. But until we find a concrete way to handle these situations, I think we should hold off on proceeding and have a discussion about how to implement the rule.

[SwetaTanwar]

I think this is a good idea. @SwetaTanwar Are you planning to submit a PR for this? If not, I can take it on.

Yes, I will be picking it up

[nzakas]

Maybe no-missing-link-fragments is more accurate?

I think it's okay for the first version to mimic the Markdownlint rule in order to allow people to easily switch to ESLint. Marking as accepted.