build: switch math rendering to mdbook-katex

Use mdbook-katex in pre-render mode for both books, pin mdBook to a compatible version, update build scripts and workflows, and replace the old MathJax regression tests with KaTeX coverage.

.github/workflows/main.yml

@@ -21,7 +21,10 @@ jobs:
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@v2
         with:
-          mdbook-version: 'latest'
+          mdbook-version: '0.4.48'
+
+      - name: Install mdBook KaTeX
+        run: cargo install mdbook-katex --locked
 
       - name: Run mdBook regression tests
         run: |
@@ -29,7 +32,8 @@ jobs:
           python3 -m unittest discover -s tests -p 'test_prepare_mdbook_zh.py'
           python3 -m unittest discover -s tests -p 'test_assemble_docs_publish_tree.py'
           python3 -m unittest discover -s tests -p 'test_ensure_book_resources.py'
-          python3 -m unittest discover -s tests -p 'test_mdbook_mathjax.py'
+          python3 -m unittest discover -s tests -p 'test_mdbook_katex.py'
+          python3 -m unittest discover -s tests -p 'test_mdbook_katex_config.py'
 
       - name: Build English HTML with mdBook
         run: bash build_mdbook.sh
@@ -49,7 +53,10 @@ jobs:
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@v2
         with:
-          mdbook-version: 'latest'
+          mdbook-version: '0.4.48'
+
+      - name: Install mdBook KaTeX
+        run: cargo install mdbook-katex --locked
 
       - name: Build Chinese HTML with mdBook
         run: bash build_mdbook_zh.sh

.github/workflows/update_docs.yml

@@ -32,7 +32,10 @@ jobs:
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@v2
         with:
-          mdbook-version: 'latest'
+          mdbook-version: '0.4.48'
+
+      - name: Install mdBook KaTeX
+        run: cargo install mdbook-katex --locked
 
       - name: Run mdBook regression tests
         run: |
@@ -40,7 +43,8 @@ jobs:
           python3 -m unittest discover -s tests -p 'test_prepare_mdbook_zh.py'
           python3 -m unittest discover -s tests -p 'test_assemble_docs_publish_tree.py'
           python3 -m unittest discover -s tests -p 'test_ensure_book_resources.py'
-          python3 -m unittest discover -s tests -p 'test_mdbook_mathjax.py'
+          python3 -m unittest discover -s tests -p 'test_mdbook_katex.py'
+          python3 -m unittest discover -s tests -p 'test_mdbook_katex_config.py'
 
       - name: Build English HTML with mdBook
         run: bash build_mdbook.sh

book.toml

@@ -11,8 +11,11 @@ create-missing = false
 [preprocessor.openmlsys]
 command = "python3 tools/mdbook_preprocessor.py"
 
+[preprocessor.katex]
+after = ["links", "openmlsys"]
+pre-render = true
+
 [output.html]
 git-repository-url = "https://github.com/openmlsys/openmlsys-zh"
-mathjax-support = true
 preferred-dark-theme = "navy"
 additional-css = ["theme/dark-mode-images.css"]

books/zh/book.toml

@@ -11,8 +11,11 @@ create-missing = false
 [preprocessor.openmlsys-zh]
 command = "python3 ../../tools/mdbook_zh_preprocessor.py"
 
+[preprocessor.katex]
+after = ["links", "openmlsys-zh"]
+pre-render = true
+
 [output.html]
 git-repository-url = "https://github.com/openmlsys/openmlsys-zh"
-mathjax-support = true
 preferred-dark-theme = "navy"
 additional-css = ["theme/dark-mode-images.css"]

books/zh/theme/head.hbs

@@ -1,10 +1 @@
-<script type="text/x-mathjax-config">
-MathJax.Hub.Config({
-  tex2jax: {
-    inlineMath: [['$', '$'], ['\\(', '\\)']],
-    displayMath: [['$$', '$$'], ['\\[', '\\]']],
-    processEscapes: true,
-    processEnvironments: true
-  }
-});
-</script>
+<!-- mdbook-katex pre-render mode does not require custom head scripts. -->

build_mdbook.sh

@@ -14,6 +14,16 @@ if ! command -v mdbook >/dev/null 2>&1; then
     exit 1
 fi
 
+if ! mdbook --version | grep -q "mdbook v0.4.48"; then
+    echo "mdbook-katex currently requires mdbook v0.4.48. Install it with: cargo install mdbook --version 0.4.48 --locked --force" >&2
+    exit 1
+fi
+
+if ! command -v mdbook-katex >/dev/null 2>&1; then
+    echo "mdbook-katex is not installed. Install it first, for example with: cargo install mdbook-katex" >&2
+    exit 1
+fi
+
 "${PYTHON_BIN}" "${ROOT}/tools/ensure_book_resources.py" --chapter-dir "${ROOT}/en_chapters"
 "${PYTHON_BIN}" "${ROOT}/tools/prepare_mdbook.py" \
     --source "${ROOT}/en_chapters" \

build_mdbook_zh.sh

@@ -14,6 +14,16 @@ if ! command -v mdbook >/dev/null 2>&1; then
     exit 1
 fi
 
+if ! mdbook --version | grep -q "mdbook v0.4.48"; then
+    echo "mdbook-katex currently requires mdbook v0.4.48. Install it with: cargo install mdbook --version 0.4.48 --locked --force" >&2
+    exit 1
+fi
+
+if ! command -v mdbook-katex >/dev/null 2>&1; then
+    echo "mdbook-katex is not installed. Install it first, for example with: cargo install mdbook-katex" >&2
+    exit 1
+fi
+
 # ── Create resource links ─────────────────────────────────────────────────────
 "${PYTHON_BIN}" "${ROOT}/tools/ensure_book_resources.py" --chapter-dir "${ROOT}/zh_chapters"
 

tests/test_mdbook_katex.py

@@ -11,10 +11,10 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 THEME_HEAD = REPO_ROOT / "theme" / "head.hbs"
 
 
-class MdBookMathJaxTests(unittest.TestCase):
-    def test_custom_head_enables_inline_dollar_math_before_mathjax_script(self) -> None:
-        if shutil.which("mdbook") is None:
-            self.skipTest("mdbook is not installed")
+class MdBookKatexTests(unittest.TestCase):
+    def test_katex_prerender_outputs_katex_markup_without_mathjax(self) -> None:
+        if shutil.which("mdbook") is None or shutil.which("mdbook-katex") is None:
+            self.skipTest("mdbook or mdbook-katex is not installed")
 
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)
@@ -26,30 +26,28 @@ class MdBookMathJaxTests(unittest.TestCase):
             (root / "book.toml").write_text(
                 """[book]
 title = "Test Book"
-language = "zh-CN"
+language = "en"
 src = "src"
 
 [build]
 build-dir = "book"
 
-[output.html]
-mathjax-support = true
+[preprocessor.katex]
+after = ["links"]
+pre-render = true
 """,
                 encoding="utf-8",
             )
             (src / "SUMMARY.md").write_text("# Summary\n\n- [Chapter](chapter.md)\n", encoding="utf-8")
-            (src / "chapter.md").write_text("# Chapter\n\nInline math $C$.\n", encoding="utf-8")
-            theme_head = THEME_HEAD.read_text(encoding="utf-8")
-            (theme / "head.hbs").write_text(theme_head, encoding="utf-8")
+            (src / "chapter.md").write_text("# Chapter\n\nInline math $C$ and block:\n\n$$x^2$$\n", encoding="utf-8")
+            (theme / "head.hbs").write_text(THEME_HEAD.read_text(encoding="utf-8"), encoding="utf-8")
 
             subprocess.run(["mdbook", "build", str(root)], check=True, capture_output=True, text=True)
 
             output = (root / "book" / "chapter.html").read_text(encoding="utf-8")
-            config_index = output.index("MathJax.Hub.Config")
-            script_index = output.index("MathJax.js?config=TeX-AMS-MML_HTMLorMML")
-
-            self.assertIn("inlineMath: [['$', '$'], ['\\\\(', '\\\\)']]", output)
-            self.assertLess(config_index, script_index)
+            self.assertIn("katex", output)
+            self.assertNotIn("MathJax.Hub.Config", output)
+            self.assertNotIn("MathJax.js", output)
 
 
 if __name__ == "__main__":

tests/test_mdbook_katex_config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class MdBookKatexConfigTests(unittest.TestCase):
+    def test_books_use_katex_prerender_and_no_mathjax_head(self) -> None:
+        book_tomls = [
+            REPO_ROOT / "book.toml",
+            REPO_ROOT / "books" / "zh" / "book.toml",
+        ]
+        head_templates = [
+            REPO_ROOT / "theme" / "head.hbs",
+            REPO_ROOT / "books" / "zh" / "theme" / "head.hbs",
+        ]
+
+        for book_toml in book_tomls:
+            content = book_toml.read_text(encoding="utf-8")
+            self.assertIn("[preprocessor.katex]", content, book_toml.as_posix())
+            self.assertIn('pre-render = true', content, book_toml.as_posix())
+            self.assertIn('after = [', content, book_toml.as_posix())
+            self.assertNotIn("mathjax-support = true", content, book_toml.as_posix())
+
+        for head_template in head_templates:
+            content = head_template.read_text(encoding="utf-8")
+            self.assertNotIn("MathJax.Hub.Config", content, head_template.as_posix())
+            self.assertNotIn("MathJax.js", content, head_template.as_posix())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_update_docs_workflow.py

@@ -24,8 +24,11 @@ class UpdateDocsWorkflowTests(unittest.TestCase):
         for workflow_path in (WORKFLOW_PATH, CI_WORKFLOW_PATH):
             workflow = workflow_path.read_text(encoding="utf-8")
             self.assertIn("uses: peaceiris/actions-mdbook@v2", workflow, workflow_path.as_posix())
-            self.assertIn("mdbook-version: 'latest'", workflow, workflow_path.as_posix())
+            self.assertIn("mdbook-version: '0.4.48'", workflow, workflow_path.as_posix())
             self.assertNotIn("cargo install mdbook --locked", workflow, workflow_path.as_posix())
+            self.assertIn("cargo install mdbook-katex --locked", workflow, workflow_path.as_posix())
+            self.assertIn("test_mdbook_katex.py", workflow, workflow_path.as_posix())
+            self.assertIn("test_mdbook_katex_config.py", workflow, workflow_path.as_posix())
 
 
 if __name__ == "__main__":

theme/head.hbs

@@ -1,10 +1 @@
-<script type="text/x-mathjax-config">
-MathJax.Hub.Config({
-  tex2jax: {
-    inlineMath: [['$', '$'], ['\\(', '\\)']],
-    displayMath: [['$$', '$$'], ['\\[', '\\]']],
-    processEscapes: true,
-    processEnvironments: true
-  }
-});
-</script>
+<!-- mdbook-katex pre-render mode does not require custom head scripts. -->