diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 44e4aa1..3e8a9f4 100644
--- a/.github/workflows/main.yml
+++ b/.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
diff --git a/.github/workflows/update_docs.yml b/.github/workflows/update_docs.yml
index 1a30e38..8d884e5 100644
--- a/.github/workflows/update_docs.yml
+++ b/.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
diff --git a/book.toml b/book.toml
index 6a5ddc9..3001e13 100644
--- a/book.toml
+++ b/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"]
diff --git a/books/zh/book.toml b/books/zh/book.toml
index 532f20a..ac5bf86 100644
--- a/books/zh/book.toml
+++ b/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"]
diff --git a/books/zh/theme/head.hbs b/books/zh/theme/head.hbs
index 793a459..08795e4 100644
--- a/books/zh/theme/head.hbs
+++ b/books/zh/theme/head.hbs
@@ -1,10 +1 @@
-
+
diff --git a/build_mdbook.sh b/build_mdbook.sh
index f814264..2a2e1ea 100644
--- a/build_mdbook.sh
+++ b/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" \
diff --git a/build_mdbook_zh.sh b/build_mdbook_zh.sh
index fff91c4..d28e162 100755
--- a/build_mdbook_zh.sh
+++ b/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"
diff --git a/tests/test_mdbook_mathjax.py b/tests/test_mdbook_katex.py
similarity index 57%
rename from tests/test_mdbook_mathjax.py
rename to tests/test_mdbook_katex.py
index 17b6c90..95f9a25 100644
--- a/tests/test_mdbook_mathjax.py
+++ b/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__":
diff --git a/tests/test_mdbook_katex_config.py b/tests/test_mdbook_katex_config.py
new file mode 100644
index 0000000..8893e0f
--- /dev/null
+++ b/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()
diff --git a/tests/test_update_docs_workflow.py b/tests/test_update_docs_workflow.py
index 68d0c76..6983122 100644
--- a/tests/test_update_docs_workflow.py
+++ b/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__":
diff --git a/theme/head.hbs b/theme/head.hbs
index 793a459..08795e4 100644
--- a/theme/head.hbs
+++ b/theme/head.hbs
@@ -1,10 +1 @@
-
+