Sphinx anchor linkcheck fails for GitHub links to Markdown files

[yukiisbored]

Observations

make linkcheck fails because Sphinx linkcheck coudn't find the "user-content-vision" anchor on https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md#user-content-vision which causes CI to fail.

Warning, treated as error:
/home/runner/work/nix.dev/nix.dev/source/contributing/documentation.md:57:broken link: https://github.com/NixOS/nix.dev/blob/master/CONTRIBUTING.md#user-content-vision (Anchor 'user-content-vision' not found)

Taken from https://github.com/NixOS/nix.dev/actions/runs/5479501955/jobs/9981419507.

Problem

It appears GitHub has made the file/markdown viewer require JavaScript as seen below:

Approaches

• Disable linkcheck anchor checks
  • Could allow for linkrot where the content is deleted from the page.
• Ignore GitHub links altogether
  • Linking to Markdown files on GitHub is a pretty common use case.
• Ignore this link
  • CI will fail if a GitHub markdown link with anchor is added.
• Find an alternative to builtin linkcheck

Willing to help?

Yes

Priorities

Add 👍 to issues you find important.

[zmitchell]

If #632 is merged can we close this issue?

[yukiisbored]

If #632 is merged can we close this issue?

I still want to find a more appropriate solution which still check whether the link itself is valid.