maint: Remove mdbook-linkcheck and support mdbook 0.5.x

roberth · roberth · commit 2636f50dd41f · 2025-12-02T02:38:30.000+01:00
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
diff --git 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
@@ -24,12 +24,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
@@ -6,7 +6,6 @@
   ninja,
   lowdown-unsandboxed,
   mdbook,
-  mdbook-linkcheck,
   jq,
   python3,
   rsync,
@@ -67,7 +66,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
@@ -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']
