Skip to content

Conversation

gukoff
Copy link
Contributor

@gukoff gukoff commented Nov 15, 2024

What are you trying to address

Problem

The current playbook recommends tcort/markdown-link-check to find dead links in the markdown files.

On our experience, this tool produces false-negative status: 0 on live URLs. This behavior is transient, but it repeats consistently. It's often the case for the Microsoft-hosted websites such as https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/.

We are forced to either ignore the URLs such as azure.microsoft.com which we would rather not do, or retry the CI task many times and hope it will eventually work.

Proposed solution

  • change the recommendation to another tool - lychee;
  • change the linting tooling for this repository to lychee;
  • fix dead links that were ignored by the previous tooling.

Why lychee

  • Popular tool, actively maintained. Pleasant interface.
  • Very fast. Can verify links in parallel from multiple threads. Similar to shiranr/linkcheck in this regard.
  • Multiplatform, integrated with megalinter, has github action.
  • Good configuration. Flexible and with reasonable defaults. Richer than markdown-link-check's configuration.
  • Seems to catch more dead links than the other tools, needs less link ignoring.
  • MIT license

Checklist

READY TO PR? Use the check-list below to ensure your branch is ready for PR.

  • Changes follow the repo structure and land in the appropriate folder and section
  • No confidential information
  • No duplicated content
  • Labeled appropriately
  • This PR was reviewed by at least one subject matter expert
  • No lint check errors related to your changes

Note: You may see link check errors on pages you have not touched. This is normal, and due to either broken links or sites that reject link checker bots. The reviewer will help you get to a green state on these.

Copy link
Contributor

@shiranr shiranr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great PR! :) very nice new tool presented and update of the doucmentation!
Thank you.

@shiranr shiranr merged commit 3eb80e8 into microsoft:main Dec 10, 2024
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants