Background

Most of our documentation sets use Sphinx Stack. For checking the links used in the documentation, we use linkcheck. This check doesn't work correctly for links that include anchors (#). For instance https://ubuntu.com/aws#get-in-touch is a valid link, but the check fails for it and flags it as a broken link.

Task

Check for different options that could help solve this problem. For instance, one option is to specify such valid URLs in the linkcheck_ignore = [] field in the project's conf.py file. But this might not be a good idea if there are many such URLs within a project.

You could also include r'.*#.*', within that same field to ignore all URLs with anchors. But this is not ideal because you are no longer checking URLs with anchors and there might actually be broken URLs that you miss.

If you can find a better solution, suggest that, with complete details of how to implement the solution.

If you want a specific documentation set to try this on, you can use https://github.com/canonical/ubuntu-cloud-docs/. It's conf.py includes the option of ignoring all links with anchors. You can remove that option and try to figure out a better solution.

Outcome

A way of checking for broken links, that doesn't have to ignore all links that use anchors and is easy to use in a sphinx setup would be awesome.

If that's not possible, a list of options tried and their pros and cons would also be useful.

Resources

Linkcheck in Sphinx stack Example repo for trials

Mentor

The mentor for this issue is @k-dimple. They are the Technical Author for Ubuntu on Public Clouds.

Please feel free to reach out to the mentor by tagging them on this issue.