From cc2ccec9b1450ac5159979b9a9e3881492012e11 Mon Sep 17 00:00:00 2001 From: John Cardinal Date: Fri, 23 Oct 2026 11:31:49 -0700 Subject: [PATCH] case 4690 - build docs: pin MkDocs below 2 (Material is incompatible with 2.0); Zensical move on the roadmap Co-Authored-By: Claude Opus 5.5 --- devdocs/build/BUILD.md | 2 +- devdocs/build/DEV-VM-SETUP.md | 2 +- devdocs/modernization/ROADMAP.md | 7 +++++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/devdocs/build/BUILD.md b/devdocs/build/BUILD.md index 91a61e98..41dbd26e 100644 --- a/devdocs/build/BUILD.md +++ b/devdocs/build/BUILD.md @@ -39,7 +39,7 @@ that can run this from scratch, use the tool list and install commands in `DEV-V | .NET SDK | 10.0.x | Server and launcher | | Node.js | **12.22.9 exactly** | Front end. Newer versions break `fibers` | | Python | 3.11 | MkDocs | -| MkDocs + mkdocs-material | current | Customer manual (`pip install mkdocs mkdocs-material`) | +| MkDocs + mkdocs-material | MkDocs 1.x | Customer manual (`pip install "mkdocs<2" mkdocs-material`). Material for MkDocs does not work with MkDocs 2.0: keep the pin until the docs move to Zensical (see `../modernization/ROADMAP.md`) | | Inno Setup | 6.x | Windows installers | | 7-Zip | current | Linux zips | | Visual Studio | 18 (2026) Community on the dev machine; no VS 2022 installed | QBI only | diff --git a/devdocs/build/DEV-VM-SETUP.md b/devdocs/build/DEV-VM-SETUP.md index e11fd3d5..c2617cd6 100644 --- a/devdocs/build/DEV-VM-SETUP.md +++ b/devdocs/build/DEV-VM-SETUP.md @@ -275,7 +275,7 @@ node -v ### 4.5 Install MkDocs ```powershell -pip install mkdocs mkdocs-material +pip install "mkdocs<2" mkdocs-material ``` Verify: diff --git a/devdocs/modernization/ROADMAP.md b/devdocs/modernization/ROADMAP.md index beffede1..53e98718 100644 --- a/devdocs/modernization/ROADMAP.md +++ b/devdocs/modernization/ROADMAP.md @@ -37,6 +37,13 @@ In this order, each step tested before the next: 5. Webpack → Vite 6. Optional: Options API → Composition API; TypeScript for new files only +## Step F, customer manual build (not part of the current port) + +MkDocs 1.x is unmaintained, and Material for MkDocs does not work with MkDocs 2.0 (the +build prints a warning to that effect since mkdocs-material 9.7). MkDocs is pinned below 2 +(`devdocs/build/BUILD.md`). Later: move the manual and customer docs to Zensical, the +Material team's successor, and check every page and link after the move. + ## Before step D starts 1. The integration suite passes, apart from the three known server bugs