docs: detect and fix broken links

[snitin315]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Resolve #16833

• Enable hyperlink to detect broken links via npm run lint:links
• Add a validate links check on CI to run this script.
• Skip/ignore linting the following links/errors:

  • All external links --skip https://

  • All nav bar links since the code for them is in a different repo. (--skip /blog --skip /play --skip /team --skip /donate --skip /docs/latest)

  • All links on old migration guides --skip migrating-to.

  • All the fragment-redirect errors since we use pretty URLs without .html. (--skip fragment-redirect)

    

  • null src for links in further reading section. For example this one . (--skip _site/rules/null)

    

Is there anything you'd like reviewers to focus on?

The CI time seems to be increased significantly with this check. Should we move docs-related checks into a separate job?

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	946173f
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/63f81aa5cf9d6100085346b3
😎 Deploy Preview	https://deploy-preview-16837--docs-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[bmish]

There's also markdown-link-check which is more popular on npm. Between that and hyperlink, which one do you think is better for us?

[snitin315]

markdown-link-check seems to work with .md files only, however not all of our links are in markdown files. For example, the reported broken link in #16833 is in a json file:

eslint/docs/src/_data/rules.json

Line 1896 in 13552c4

"description": "These rules have been deprecated in accordance with the <a href=\"/docs/use/rule-deprecation\">deprecation policy</a>, and replaced by newer rules:",

So I believe markdown-link-check won't be able to detect such broken links. Whereas hyperlink runs on the generated HTML files so it can detect such links.

[snitin315]

Seeing a strange issue on CI, (FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory) debugging it.

[harish-sethuraman]

LGTM. Can we do the same for eslint.org as well?

[amareshsm]

LGTM 🎉

[snitin315]

Can we do the same for eslint.org as well?

@harish-sethuraman sure, I'll send a PR to the eslint.org repo as well 👍🏻

[nzakas]

Folks - please remember, if you approve a PR but don't merge it, explain why you didn't merge it. If you want someone else specific to review it, at-mention them; if you want another approval before merging, just say that. That way, we can know if something is ready to merge. We'd like to get PRs merged as quickly as possible and this will really help. Thanks!

[snitin315]

It seems the merging is blocked, and since I can't approve my own PR I would need another approval from @eslint/eslint-tsc to enable merging.

[nzakas]

We just need to wait for after a potential patch release before merging.

[nzakas]

I tried running this locally before merging, and it doesn't appear to work:

$ npm run lint:links

> docs-eslint@8.33.0 lint:links
> hyperlink ./_site/index.html --canonicalroot https://eslint.org/docs/head/ -r --internal ./_site/index.html --pretty --skip https:// --skip fragment-redirect --skip migrating-to --skip /blog --skip /play --skip /team --skip /donate --skip /docs/latest --skip _site/rules/null > internal-links.tap; cat internal-links.tap | tap-spot

Guessing --root from input files: file:///C:/Users/nzaka/projects/eslint/eslint/docs
  

  0 tests
  0 passed

I am running from within /docs and verified that docs/_site exists. Is there another step required?

[snitin315]

That should work. If you are using windows, I'm not sure if the > internal-links.tap; cat internal-links.tap | tap-spot part of the script is compatible with windows. Can you remove that and run the script and run it again?

[nzakas]

Yup, now I'm seeing output. Rather than using tap-spot, it would probably make sense to create a JS file in the tools directory that runs Hyperlink, collects the output, and displays it in a pretty format. That way it'll work across all operating systems.

[mdjermanovic]

LGTM, thanks! I'm leaving this open for others to review again because it's significantly different now.

[mdjermanovic]

Also, there are merge conflicts in docs/package.json.

[snitin315]

@nzakas Can you once confirm if you are able to run it locally now?

[mdjermanovic]

This file is autogenerated during releases, so we should also update the template:

https://github.com/eslint/eslint/blob/main/conf/rule-type-list.json

Otherwise, next release will overwrite these changes. You can run node Makefile.js generateRuleIndexPage to verify.

[snitin315]

Thanks for the catch, fixed in 946173f

[mdjermanovic]

LGTM, thanks! Leaving this open for @nzakas to verify.

[nzakas]

Confirmed it works for me. Thanks!