Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
1 task done
SwetaTanwar opened this issue May 10, 2025 · 6 comments · May be fixed by #380
Open
1 task done

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

SwetaTanwar opened this issue May 10, 2025 · 6 comments · May be fixed by #380
Assignees

Comments

@SwetaTanwar
Copy link
Contributor

SwetaTanwar commented May 10, 2025

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

@eslintbot eslintbot added this to Triage May 10, 2025
@github-project-automation github-project-automation bot moved this to Needs Triage in Triage May 10, 2025
@snitin315
Copy link
Contributor

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

@snitin315
Copy link
Contributor

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

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

@snitin315 snitin315 moved this from Needs Triage to Ready to Implement in Triage May 10, 2025
@Pixel998
Copy link
Contributor

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
Copy link
Member

lumirlumir commented May 10, 2025

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
Copy link
Contributor Author

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
Copy link
Member

nzakas commented May 12, 2025

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.

@SwetaTanwar SwetaTanwar linked a pull request May 19, 2025 that will close this issue
1 task
@lumirlumir lumirlumir moved this from Ready to Implement to Implementing in Triage May 26, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Implementing
Development

Successfully merging a pull request may close this issue.

5 participants