Merge pull request #372 from yukiisbored/linkcheck-gh-fail

Rewrite GitHub anchor links to `user-content-`

CONTRIBUTING.md

@@ -183,3 +183,18 @@ Collect links at the end of each section, which are delimited by headings.
 
 [Here is a discussion of different line wrapping styles.]: https://web.archive.org/web/20220519121408/https://mtsknn.fi/blog/4-1-wrapping-styles-for-markdown-prose-and-code-comments/
 [reference links]: https://github.github.com/gfm/#reference-link
+
+### Notes
+
+#### GitHub heading anchors fails linkcheck
+
+Due to a [Sphinx bug][linkcheck gh bug], linkcheck fails when it verifies the
+existence of GitHub heading anchors on rendered Markdown documents.
+
+Until the bug is resolved, add the `user-content-` prefix to GitHub links
+containing heading anchors.
+
+For example, instead of
+`https://github.com/cachix/install-nix-action#user-content-how-can-i-run-nixos-tests`,
+use
+`https://github.com/cachix/install-nix-action#user-content-how-can-i-run-nixos-tests`. 

source/conf.py

@@ -414,10 +414,6 @@ linkcheck_anchors_ignore = [
     r"instance_type",
     r"authentication",
     r"community",
-    # Seems like README anchors aren't parsable?
-    r"cross-compiling",
-    r"supported-formats",
-    r"how-can-i-run-nixos-tests",
 ]
 
 

source/tutorials/building-bootable-iso-image.md

@@ -1,7 +1,7 @@
 # Building a bootable ISO image
 
 :::{note}
-If you need to build images for a different platform, see [Cross compiling](https://github.com/nix-community/nixos-generators#cross-compiling).
+If you need to build images for a different platform, see [Cross compiling](https://github.com/nix-community/nixos-generators#user-content-cross-compiling).
 :::
 
 You may find that an official installation image lacks some hardware support.
@@ -37,4 +37,4 @@ $ sync
 
 ## Next steps
 
-- Take a look at this [list of formats that generators support](https://github.com/nix-community/nixos-generators#supported-formats) to find your cloud provider or virtualization technology.
+- Take a look at this [list of formats that generators support](https://github.com/nix-community/nixos-generators#user-content-supported-formats) to find your cloud provider or virtualization technology.

source/tutorials/integration-testing-using-virtual-machines.md

@@ -214,5 +214,5 @@ Linux server 5.10.37 #1-NixOS SMP Fri May 14 07:50:46 UTC 2021 x86_64 GNU/Linux
 
 - Running integration tests on CI requires hardware acceleration, which many CIs do not support.
   To run integration tests on {ref}`GitHub Actions <github-actions>` see
-  [how to disable hardware acceleration](https://github.com/cachix/install-nix-action#how-can-i-run-nixos-tests).
+  [how to disable hardware acceleration](https://github.com/cachix/install-nix-action#user-content-how-can-i-run-nixos-tests).
 - NixOS comes with a large set of tests that serve also as educational examples. A good inspiration is [Matrix bridging with an IRC](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/matrix/appservice-irc.nix).