nix.dev
nix.dev copied to clipboard
Sphinx anchor linkcheck fails for GitHub links to Markdown files
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 :+1: to issues you find important.
If #632 is merged can we close this issue?
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.