From d5c8289f1e39397fcf562fa750719e9e86569041 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 3 Jan 2023 10:29:05 +0100
Subject: [PATCH] doc/manual: Document hacking on the manual links

---
 doc/manual/src/contributing/hacking.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index c9da1962f..cd3788efc 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -249,3 +249,22 @@ search/replaced in it for each new build.
 The installer now supports a `--tarball-url-prefix` flag which _may_ have
 solved this need?
 -->
+
+### Checking the manual links
+
+The build checks for broken internal links, but this happens late in the process,
+so `nix build .` is not suitable for iterating. To check the manual incrementally, run:
+
+```console
+make html -j $NIX_BUILD_CORES
+```
+
+When iterating on the makefile, run:
+
+```console
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
+```
+
+If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
+
+`mdbook-linkcheck` does not implement fragment checking yet.