Rewrite GitHub anchor links to user-content-

[yukiisbored]

Due to an Sphinx issue, linkcheck fails on GitHub anchors for
GitHub rendered documents.

This change rewrites the anchors to the ones that can be verified by
linkcheck.

[zupo]

I don't understand why we want this, can you explain a bit please?

[yukiisbored]

I don't understand why we want this, can you explain a bit please?

For some reason, the linkcheck builder fails when it tries to check heading anchors on a GitHub page with Markdown

This PR simply removes the GitHub specific cases with a more generic "ignore all pages from GitHub".

For example, cross-compiling refers to https://github.com/NixOS/nix.dev/blob/master/source/tutorials/building-bootable-iso-image.md?plain=1#L4 which contains a link to https://github.com/nix-community/nixos-generators#cross-compiling

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-10-28-documentation-team-meeting-13/22806/1

[yukiisbored]

Found the upstream (Sphinx) issue on this: sphinx-doc/sphinx#9016
Following the conversation there's a workaround but it is disabled: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/linkcheck.py#L585-L587 (sphinx-doc/sphinx#9435)

It seems the regex option to capture github.com URLs won't work because linkcheck_anchors_ignore only captures the anchor part of the URL: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/linkcheck.py#L585-L587

[yukiisbored]

There's a workaround where user-content-<heading> is used over <heading> (e.x https://github.com/cachix/install-nix-action#user-content-how-can-i-run-nixos-tests instead of https://github.com/cachix/install-nix-action#user-content-how-can-i-run-nixos-tests).

Though, the heading won't be visible as it's covered by some GitHub UI element.

[yukiisbored]

There are two options as far as I see:

1. Disable anchor link checks altogether.
2. Use user-content- anchors. Hopefully until Sphinx fix the issue.

I'm gonna opt for the second option on this pull-request for now and add a note in CONTRIBUTING.md

[zupo]

I'd very much like to keep anchor links checks. It's really discouraging to newcomers when docs point to bad URLs.

There is a third way too: fix/patch/monkeypatch or even fork Sphinx so link checking works for us.

[zupo]

Awesome find 👍 👍