rust-lang · jeanas · Nov 29, 2025
diff --git a/crates/mdbook-core/src/config.rs b/crates/mdbook-core/src/config.rs
@@ -460,7 +460,9 @@ pub struct HtmlConfig {
     pub definition_lists: bool,
     /// Support for admonitions.
     pub admonitions: bool,
-    /// Should mathjax be enabled?
+    /// Parse and render `$...$` and `$$...$$` as math formulas.
+    pub math: bool,
+    /// Legacy math support.
     pub mathjax_support: bool,
     /// Additional CSS stylesheets to include in the rendered page's `<head>`.
     pub additional_css: Vec<PathBuf>,
@@ -529,6 +531,7 @@ impl Default for HtmlConfig {
             smart_punctuation: true,
             definition_lists: true,
             admonitions: true,
+            math: false,
             mathjax_support: false,
             additional_css: Vec::new(),
             additional_js: Vec::new(),

diff --git a/crates/mdbook-html/front-end/templates/index.hbs b/crates/mdbook-html/front-end/templates/index.hbs
@@ -45,8 +45,36 @@
         <link rel="stylesheet" href="{{ resource this }}">
         {{/each}}
 
-        {{#if mathjax_support}}
-        <!-- MathJax -->
+        {{#if math}}
+        <!-- Load MathJax -->
+        {{! MathJax normally looks for math tags in the page content. In our case,
+            the math tags are parsed in the Markdown input by pulldown-cmark and
+            converted to <span> tags with special CSS classes. This bit of code
+            tells MathJax to render these and only these. Adapted from
+            <https://docs.mathjax.org/en/latest/upgrading/v2.html#math-script-example> }}
+        <script>
+        MathJax = {
+          options: {
+            renderActions: {
+              find: [10, function (doc) {
+                for (const node of document.querySelectorAll('span.math-inline, span.math-display')) {
+                  const display = node.classList.contains('math-display');
+                  const math = new doc.options.MathItem(node.textContent, doc.inputJax[0], display);
+                  const text = document.createTextNode('');
+                  node.parentNode.replaceChild(text, node);
+                  math.start = {node: text, delim: '', n: 0};
+                  math.end = {node: text, delim: '', n: 0};
+                  doc.math.push(math);
+                }
+              }, '']
+            }
+          }
+        };
+        </script>
+        <script defer src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js"></script>
+        {{else if mathjax_support}}
+        <!-- Load MathJax -->
+        {{! Legacy MathJax support that just tells MathJax to look for math tags in the page content }}
         <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
         {{/if}}
 

diff --git a/crates/mdbook-html/src/html/mod.rs b/crates/mdbook-html/src/html/mod.rs
@@ -53,6 +53,7 @@ impl<'a> HtmlRenderOptions<'a> {
         markdown_options.smart_punctuation = config.smart_punctuation;
         markdown_options.definition_lists = config.definition_lists;
         markdown_options.admonitions = config.admonitions;
+        markdown_options.math = config.math;
         HtmlRenderOptions {
             markdown_options,
             path,

diff --git a/crates/mdbook-html/src/html_handlebars/hbs_renderer.rs b/crates/mdbook-html/src/html_handlebars/hbs_renderer.rs
@@ -506,6 +506,10 @@ fn make_data(
         json!(preferred_dark_theme),
     );
 
+    if html_config.math {
+        data.insert("math".to_owned(), json!(true));
+    }
+
     if html_config.mathjax_support {
         data.insert("mathjax_support".to_owned(), json!(true));
     }

diff --git a/crates/mdbook-markdown/src/lib.rs b/crates/mdbook-markdown/src/lib.rs
@@ -28,6 +28,11 @@ pub struct MarkdownOptions {
     ///
     /// This is `true` by default.
     pub admonitions: bool,
+    /// Enables `$...$` and `$$...$$` syntax for inline and display math,
+    /// respectively.
+    ///
+    /// This is `false` by default.
+    pub math: bool,
 }
 
 impl Default for MarkdownOptions {
@@ -36,6 +41,7 @@ impl Default for MarkdownOptions {
             smart_punctuation: true,
             definition_lists: true,
             admonitions: true,
+            math: false,
         }
     }
 }
@@ -57,5 +63,8 @@ pub fn new_cmark_parser<'text>(text: &'text str, options: &MarkdownOptions) -> P
     if options.admonitions {
         opts.insert(Options::ENABLE_GFM);
     }
+    if options.math {
+        opts.insert(Options::ENABLE_MATH);
+    }
     Parser::new_ext(text, opts)
 }
diff --git a/guide/book.toml b/guide/book.toml
@@ -9,7 +9,7 @@ edition = "2018"
 
 [output.html]
 smart-punctuation = true
-mathjax-support = true
+math = true
 site-url = "/mdBook/"
 git-repository-url = "https://github.com/rust-lang/mdBook/tree/master/guide"
 edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"

diff --git a/guide/src/format/configuration/renderers.md b/guide/src/format/configuration/renderers.md
@@ -100,7 +100,7 @@ preferred-dark-theme = "navy"
 smart-punctuation = true
 definition-lists = true
 admonitions = true
-mathjax-support = false
+math = false
 additional-css = ["custom.css", "custom2.css"]
 additional-js = ["custom.js"]
 no-section-label = false
@@ -129,7 +129,7 @@ The following configuration options are available:
   Defaults to `true`.
 - **definition-lists:** Enables [definition lists](../markdown.md#definition-lists). Defaults to `true`.
 - **admonitions:** Enables [admonitions](../markdown.md#admonitions). Defaults to `true`.
-- **mathjax-support:** Adds support for [MathJax](../mathjax.md). Defaults to
+- **math:** Enables [support for math formulas](../mathjax.md). Defaults to
   `false`.
 - **additional-css:** If you need to slightly change the appearance of your book
   without overwriting the whole style, you can specify a set of stylesheets that

diff --git a/guide/src/format/mathjax.md b/guide/src/format/mathjax.md
@@ -1,43 +1,33 @@
 # MathJax support
 
-mdBook has optional support for math equations through
-[MathJax](https://www.mathjax.org/).
-
-To enable MathJax, you need to add the `mathjax-support` key to your `book.toml`
-under the `output.html` section.
+mdBook has optional support for math formulas, which are rendered through
+[MathJax](https://www.mathjax.org/) (more precisely, the latest release of
+MathJax version 4). To enable it, set `output.html.math` to `true` in your
+`book.toml`:
 
 ```toml
 [output.html]
-mathjax-support = true
+math = true
 ```
 
->**Note:** The usual delimiters MathJax uses are not yet supported. You can't
-currently use `$$ ... $$` as delimiters and the `\[ ... \]` delimiters need an
-extra backslash to work. Hopefully this limitation will be lifted soon.
+Inline equations are delimited by `$...$` and block equations are delimited
+by `$$...$$`. For example, to obtain
 
->**Note:** When you use double backslashes in MathJax blocks (for example in
-> commands such as `\begin{cases} \frac 1 2 \\ \frac 3 4 \end{cases}`) you need
-> to add _two extra_ backslashes (e.g., `\begin{cases} \frac 1 2 \\\\ \frac 3 4
-> \end{cases}`).
+> If $n \geq 3$ then there are no integers $a, b, c \geq 1$ satisfying $$a^n + b^n = c^n$$
 
+you would write the following:
 
-### Inline equations
-Inline equations are delimited by `\\(` and `\\)`. So for example, to render the
-following inline equation \\( \int x dx = \frac{x^2}{2} + C \\) you would write
-the following:
 ```
-\\( \int x dx = \frac{x^2}{2} + C \\)
+If $n \geq 3$ then there are no integers $a, b, c \geq 1$ satisfying $$a^n + b^n = c^n$$
 ```
 
-### Block equations
-Block equations are delimited by `\\[` and `\\]`. To render the following
-equation
-
-\\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
-
+## Legacy MathJax support
 
-you would write:
-
-```bash
-\\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
-```
+The legacy option `output.html.mathjax-support` enables equations with a
+different syntax: `\\( ... \\)` for inline equations and `\\[ ... \\]` for
+block equations. Because it does not parse formulas in the Markdown input
+but instead lets MathJax find the delimiters in the HTML output, it has
+the limitation that characters which have an effect in Markdown, such as
+underscores, need to be escaped in formulas. This option is kept for
+backwards compatibility; use `output.html.math` in new books. It uses
+MathJax 2.7.1.
diff --git a/tests/testsuite/markdown.rs b/tests/testsuite/markdown.rs
@@ -164,6 +164,19 @@ fn definition_lists() {
         );
 }
 
+#[test]
+fn math() {
+    BookTest::from_dir("markdown/math")
+        .check_all_main_files()
+        .run("build", |cmd| {
+            cmd.env("MDBOOK_OUTPUT__HTML__MATH", "true");
+        })
+        .check_main_file(
+            "book/math.html",
+            file!["markdown/math/expected_enabled/math.html"],
+        );
+}
+
 #[test]
 fn admonitions() {
     BookTest::from_dir("markdown/admonitions")

diff --git a/tests/testsuite/markdown/math/book.toml b/tests/testsuite/markdown/math/book.toml
@@ -0,0 +1,2 @@
+[book]
+title = "math"
diff --git a/tests/testsuite/markdown/math/expected/math.html b/tests/testsuite/markdown/math/expected/math.html
@@ -0,0 +1,2 @@
+<p>Inline math: $(a+b)^2 = a^2 + 2ab + b^2$</p>
+<p>Display math: $$(a+b)^2 = a^2 + 2ab + b^2$$</p>
diff --git a/tests/testsuite/markdown/math/expected_enabled/math.html b/tests/testsuite/markdown/math/expected_enabled/math.html
@@ -0,0 +1,2 @@
+<p>Inline math: <span class="math math-inline">(a+b)^2 = a^2 + 2ab + b^2</span></p>
+<p>Display math: <span class="math math-display">(a+b)^2 = a^2 + 2ab + b^2</span></p>
diff --git a/tests/testsuite/markdown/math/src/SUMMARY.md b/tests/testsuite/markdown/math/src/SUMMARY.md
@@ -0,0 +1,3 @@
+# Summary
+
+- [Math formulas](math.md)
diff --git a/tests/testsuite/markdown/math/src/math.md b/tests/testsuite/markdown/math/src/math.md
@@ -0,0 +1,3 @@
+Inline math: $(a+b)^2 = a^2 + 2ab + b^2$
+
+Display math: $$(a+b)^2 = a^2 + 2ab + b^2$$
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		<p>Inline math: $(a+b)^2 = a^2 + 2ab + b^2$</p>
		<p>Display math: $$(a+b)^2 = a^2 + 2ab + b^2$$</p>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		<p>Inline math: <span class="math math-inline">(a+b)^2 = a^2 + 2ab + b^2</span></p>
		<p>Display math: <span class="math math-display">(a+b)^2 = a^2 + 2ab + b^2</span></p>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Inline math: $(a+b)^2 = a^2 + 2ab + b^2$

		Display math: $$(a+b)^2 = a^2 + 2ab + b^2$$