diff --git a/doc/manual/anchors.jq b/doc/manual/anchors.jq
index 72309779c..4fd944958 100644
--- a/doc/manual/anchors.jq
+++ b/doc/manual/anchors.jq
@@ -24,8 +24,8 @@ 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)),
-    };
+	# XXX FUTURE: drop sections once mdBook is at 0.5.0 or above in nixpkgs
+	$body | (.items? // .sections) |= map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end))
+	;
 
 process_command
diff --git a/doc/manual/book.toml b/doc/manual/book.toml
index 228d6328e..f070922bd 100644
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml
@@ -22,20 +22,21 @@ fold.level = 30
 # not want to disable the links preprocessor entirely though because that requires
 # disabling *all* built-in preprocessors and selectively reenabling those we want.
 [preprocessor.substitute]
-command = "python3 doc/manual/substitute.py"
+command = "python3 substitute.py"
 before = ["anchors", "links"]
 
 [preprocessor.anchors]
 renderers = ["html"]
-command = "jq --from-file doc/manual/anchors.jq"
+command = "jq --from-file anchors.jq"
 
 [output.markdown]
 
-[output.linkcheck]
+# XXX FUTURE: may be reenabled once mdBook 0.5.0 or above and matching mdbook-linkchecker are in nixpkgs
+#[output.linkcheck]
 # no Internet during the build (in the sandbox)
-follow-web-links = false
+#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"
+#warning-policy = "ignore"
diff --git a/doc/manual/meson.build b/doc/manual/meson.build
index f7763d19a..85a5bb802 100644
--- a/doc/manual/meson.build
+++ b/doc/manual/meson.build
@@ -42,8 +42,9 @@ manual = custom_target(
     '-c',
     '''
         @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
+        cd @3@
+        @1@ build . -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
         cd @SOURCE_ROOT@
-        @1@ build doc/manual -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
         rm -rf @2@/manual
         mv @2@/html @2@/manual
         find @2@/manual -iname meson.build -delete
@@ -51,6 +52,7 @@ manual = custom_target(
       python.full_path(),
       mdbook.full_path(),
       meson.current_build_dir(),
+      meson.current_source_dir()
     ),
   ],
   input : [
@@ -81,7 +83,7 @@ manual = custom_target(
   depfile : 'manual.d',
   env : {
     'RUST_LOG': 'info',
-    'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
+    'MANUAL_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
   },
 )
 manual_md = manual[1]
diff --git a/doc/manual/substitute.py b/doc/manual/substitute.py
index 6a140305e..d14c4ca13 100755
--- a/doc/manual/substitute.py
+++ b/doc/manual/substitute.py
@@ -70,9 +70,10 @@ def do_include(content: str, relative_md_path: Path, source_root: Path, search_p
 
 def recursive_replace(data, book_root, search_path):
     match data:
-        case {'sections': sections}:
+        # XXX FUTURE: drop sections once mdBook is at 0.5.0 or above in nixpkgs
+        case {'sections': items} | {'items': items}:
             return data | dict(
-                sections = [recursive_replace(section, book_root, search_path) for section in sections],
+                items = [recursive_replace(item, book_root, search_path) for item in items],
             )
         case {'Chapter': chapter}:
             path_to_chapter = Path(chapter['path'])
@@ -119,10 +120,10 @@ def main():
     context, book = json.load(sys.stdin)
 
     # book_root is the directory where book contents leave (ie, src/)
-    book_root = Path(context['root']) / context['config']['book']['src']
+    book_root = Path(context['root']) / context['config']['book'].get('src', 'src')
 
     # includes pointing into @generated@ will look here
-    search_path = Path(os.environ['MDBOOK_SUBSTITUTE_SEARCH'])
+    search_path = Path(os.environ['MANUAL_SUBSTITUTE_SEARCH'])
 
     # Find @var@ in all parts of our recursive book structure.
     replaced_content = recursive_replace(book, book_root, search_path)
diff --git a/package.nix b/package.nix
index 94f435fb9..f8a3e46e1 100644
--- a/package.nix
+++ b/package.nix
@@ -335,7 +335,10 @@ stdenv.mkDerivation (finalAttrs: {
   ]
   ++ [
     (lib.getBin lowdown-unsandboxed)
-    mdbook
+    (lib.warnIf (lib.versionAtLeast mdbook.version "0.5.0")
+      "Workarounds for mdbook 0.4.x/0.5.x interoperability can be removed when 0.5.0 or above is in nixpkgs-stable"
+      mdbook
+    )
     mdbook-linkcheck
   ]
   ++ [