From 6ac33ab878f5f51060f5d4dbdcfca6b9a0d1a8de Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 2 Dec 2025 02:37:37 +0100
Subject: [PATCH 1/2] maint: Remove mdbook-linkcheck and support mdbook 0.5.x

Fixes #14628

- Remove mdbook-linkcheck dependency and configuration (was blocking
  upgrades to mdbook 0.5.0+, configured with warning-policy = "ignore"
  due to false positives, and redundant with lychee-based link checking)
- Update substitute.py and anchors.jq to handle 'items' (mdbook 0.5.x)
  in addition to 'sections' (mdbook 0.4.x), as per mdbook 0.5.0
  changelog: "Book::sections was renamed to Book::items"
  https://github.com/rust-lang/mdBook/blob/master/CHANGELOG.md#05-migration-guide

(cherry picked from commit 2636f50dd41fe357ec64430aeeb772328ab2d7cb)
---
 doc/manual/anchors.jq    | 13 ++++++++++---
 doc/manual/book.toml.in  |  9 ---------
 doc/manual/package.nix   |  2 --
 doc/manual/substitute.py |  4 ++++
 4 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/doc/manual/anchors.jq b/doc/manual/anchors.jq
index 72309779c..83ff3fcca 100755
--- a/doc/manual/anchors.jq
+++ b/doc/manual/anchors.jq
@@ -24,8 +24,15 @@ def map_contents_recursively(transformer):
 def process_command:
     .[0] as $context |
     .[1] as $body |
-    $body + {
-        sections: $body.sections | map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end)),
-    };
+    # mdbook 0.5.x uses 'items' instead of 'sections'
+    if $body.items then
+        $body + {
+            items: $body.items | map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end)),
+        }
+    else
+        $body + {
+            sections: $body.sections | map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end)),
+        }
+    end;
 
 process_command
diff --git a/doc/manual/book.toml.in b/doc/manual/book.toml.in
index 34acf642e..a65adb045 100644
--- a/doc/manual/book.toml.in
+++ b/doc/manual/book.toml.in
@@ -23,12 +23,3 @@ renderers = ["html"]
 command = "jq --from-file ./anchors.jq"
 
 [output.markdown]
-
-[output.linkcheck]
-# no Internet during the build (in the sandbox)
-follow-web-links = false
-
-# mdbook-linkcheck does not understand [foo]{#bar} style links, resulting in
-# excessive "Potential incomplete link" warnings. No other kind of warning was
-# produced at the time of writing.
-warning-policy = "ignore"
diff --git a/doc/manual/package.nix b/doc/manual/package.nix
index 69b7c0e49..2b11fa2b0 100644
--- a/doc/manual/package.nix
+++ b/doc/manual/package.nix
@@ -6,7 +6,6 @@
   ninja,
   lowdown-unsandboxed,
   mdbook,
-  mdbook-linkcheck,
   jq,
   python3,
   rsync,
@@ -51,7 +50,6 @@ mkMesonDerivation (finalAttrs: {
     ninja
     (lib.getBin lowdown-unsandboxed)
     mdbook
-    mdbook-linkcheck
     jq
     python3
     rsync
diff --git a/doc/manual/substitute.py b/doc/manual/substitute.py
index 6e27c3388..106dcf17d 100644
--- a/doc/manual/substitute.py
+++ b/doc/manual/substitute.py
@@ -41,6 +41,10 @@ def recursive_replace(data: dict[str, t.Any], book_root: Path, search_path: Path
             return data | dict(
                 sections = [recursive_replace(section, book_root, search_path) for section in sections],
             )
+        case {'items': items}:
+            return data | dict(
+                items = [recursive_replace(item, book_root, search_path) for item in items],
+            )
         case {'Chapter': chapter}:
             path_to_chapter = Path(chapter['path'])
             chapter_content = chapter['content']

From de4df1e90bab8079de78e0bb51170a56b42f5084 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 2 Dec 2025 02:38:08 +0100
Subject: [PATCH 2/2] maint: Fix lowdown override compatibility with newer
 nixpkgs

Use `or ""` fallback for postInstall attribute which may not exist in
newer nixpkgs versions of lowdown.

(cherry picked from commit 0aef1ddb9ee5b706be03e4956af9300fdbed4a97)
---
 packaging/dependencies.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packaging/dependencies.nix b/packaging/dependencies.nix
index 7f815f128..30629464e 100644
--- a/packaging/dependencies.nix
+++ b/packaging/dependencies.nix
@@ -54,7 +54,7 @@ scope: {
     nativeBuildInputs = prevAttrs.nativeBuildInputs ++ [ pkgs.buildPackages.bmake ];
     postInstall =
       lib.replaceStrings [ "lowdown.so.1" "lowdown.1.dylib" ] [ "lowdown.so.2" "lowdown.2.dylib" ]
-        prevAttrs.postInstall;
+        (prevAttrs.postInstall or "");
   });
 
   # TODO: Remove this when https://github.com/NixOS/nixpkgs/pull/442682 is included in a stable release