From 96b03ada48333835bfca9eed82c052a9ba940f85 Mon Sep 17 00:00:00 2001
From: classabbyamp <void@placeviolette.net>
Date: Mon, 12 Jan 2026 01:21:46 -0500
Subject: [PATCH 1/2] use mdbook-legacy as a workaround for compatibility
 issues

Ref: void-linux/void-docs#840
Ref: void-linux/void-docs#841
---
 .github/workflows/ci.yaml | 2 +-
 CONTRIBUTING.md           | 2 +-
 Makefile                  | 3 ++-
 README.md                 | 2 +-
 check.sh                  | 4 ++--
 5 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 995f3791f..c2fc82d31 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -51,7 +51,7 @@ jobs:
         run: |
           xbps-install -Syu || xbps-install -Syu xbps
           xbps-install -yu
-          xbps-install -y mdbook-linkcheck bash git
+          xbps-install -y mdBook-legacy mdbook-linkcheck bash git
       - name: Checkout
         id: checkout
         uses: classabbyamp/treeless-checkout-action@v1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 471b4d8fb..960957b3a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -327,7 +327,7 @@ You can then edit the repository files as appropriate.
 
 ### Making changes
 
-To serve the docs locally and view your changes, run `mdbook serve` from the
+To serve the docs locally and view your changes, run `mdbook-legacy serve` from the
 root of the repository.
 
 Once you're satisfied with your changes, run the `check.sh` script provided in
diff --git a/Makefile b/Makefile
index dd20fe591..5293815eb 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,6 @@
 PREFIX := /usr/local
 
+MDBOOK := /usr/bin/mdbook-legacy
 SOURCES = $(shell find src -not -path 'src/theme*' -type f -name '*.md')
 MANPAGES = $(subst src/,book/mandoc/,$(patsubst %.md,%.7,$(SOURCES)))
 UTILS = book/void-docs book/void-docs.1
@@ -25,7 +26,7 @@ $(UTILS): book/%: res/%.in book
 	sed -e "s,@PREFIX@,$(PREFIX)," $< >$@
 
 void-book: $(SOURCES) book/typst/handbook-cover.svg
-	mdbook build
+	$(MDBOOK) build
 
 book/typst/handbook-cover.svg: res/handbook-cover.svg book/typst
 	cp -a $< $@
diff --git a/README.md b/README.md
index bdfb947af..aef05e7e9 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ the same protocol as the packages tree. For details, please read
 The `Makefile` builds HTML, roff and PDF versions of the Void documentation and
 the `void-docs.1` man page. It requires the following Void packages:
 
-- `mdBook`
+- `mdBook-legacy`
 - `findutils`
 - `lowdown` (version 0.8.1 or greater)
 - `mdbook-typst`
diff --git a/check.sh b/check.sh
index 30fb2a897..cc12b80a8 100755
--- a/check.sh
+++ b/check.sh
@@ -60,9 +60,9 @@ fi
 
 vmdfmt -l -w src/
 
-if command -v mdbook >/dev/null 2>&1; then
+if command -v mdbook-legacy >/dev/null 2>&1; then
     echo "Building book and checking links with mdbook ..."
-    mdbook build
+    mdbook-legacy build
 else
     echo "Checking links with mdbook-linkcheck ..."
     mdbook-linkcheck -s

From 94aa0af7d9142623b11378863cf8201734690527 Mon Sep 17 00:00:00 2001
From: classabbyamp <void@placeviolette.net>
Date: Mon, 12 Jan 2026 01:29:48 -0500
Subject: [PATCH 2/2] book.toml: add gnu.org to linkcheck exclusions

---
 book.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/book.toml b/book.toml
index 278114c78..59272997a 100644
--- a/book.toml
+++ b/book.toml
@@ -75,5 +75,6 @@ exclude = [
 	'canonical\.com',
 	'freedesktop\.org',
 	'libressl\.org',
+	'gnu\.org',
 ]
 user-agent = "Mozilla/5.0"