From b9cf38a5d1e477a57fe00dc5f721106440e28ca9 Mon Sep 17 00:00:00 2001 From: cydia2001 Date: Wed, 11 Mar 2026 02:27:46 +0000 Subject: [PATCH] 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 | 13 +++++-- .github/workflows/update_docs.yml | 8 +++-- book.toml | 5 ++- books/zh/book.toml | 5 ++- books/zh/theme/head.hbs | 11 +----- build_mdbook.sh | 10 ++++++ build_mdbook_zh.sh | 10 ++++++ ...mdbook_mathjax.py => test_mdbook_katex.py} | 28 +++++++-------- tests/test_mdbook_katex_config.py | 35 +++++++++++++++++++ tests/test_update_docs_workflow.py | 5 ++- theme/head.hbs | 11 +----- 11 files changed, 98 insertions(+), 43 deletions(-) rename tests/{test_mdbook_mathjax.py => test_mdbook_katex.py} (57%) create mode 100644 tests/test_mdbook_katex_config.py 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 @@ - +