Configurable MathJax Support

guide/book.toml

@@ -8,11 +8,13 @@ language = "en"
 edition = "2018"
 
 [output.html]
-mathjax-support = 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}"
 
+[output.html.mathjax]
+enable = true
+
 [output.html.playground]
 editable = true
 line-numbers = true

guide/src/format/mathjax.md

@@ -3,14 +3,6 @@
 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.
-
-```toml
-[output.html]
-mathjax-support = 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.
@@ -41,3 +33,66 @@ you would write:
 ```bash
 \\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
 ```
+
+## MathJax 2
+
+To enable MathJax 2, you need to add the `mathjax-support` key to your `book.toml`
+under the `output.html` section.
+
+```toml
+[output.html]
+mathjax-support = true
+```
+
+## MathJax 3
+
+To enable MathJax 3, you need to add the `enable` key to your `book.toml`
+under the `output.html.mathjax` section.
+
+```toml
+[output.html.mathjax]
+enable = true
+```
+>**Note:** Remove or set to the `false` value the `mathjax-support` key
+> under the `output.html` section if you set it previously.
+
+Additionaly you can set `config` key to select used [configuration][comb-comp].
+You can select one of:
+
+| Value | Input | Output | Default
+| :-- | :-- | :-- | :--
+| tex-chtml | tex | chtml |
+| tex-chtml-full | tex | chtml |
+| tex-svg | tex | svg |
+| tex-svg-full | tex | svg |
+| tex-mml-chtml | tex, mml | chtml | yes
+| tex-mml-svg | tex, mml | svg |
+| mml-chtml | mml | chtml |
+| mml-svg | mml | svg |
+
+Use the `source` key to set used MathJax distribution.
+If value starts with `/` symbol it will be interpreted relative
+to [source/build](configuration/general.md) directory.
+By default the builtin copy of MathJax with `/mathjax/es5` value is used.
+But you can set some value like the `https://cdn.jsdelivr.net/npm/mathjax@3/es5`
+to use MathJax from CDN.
+
+For example to use local MathJax copy for tex input and svg output you can
+do something like:
+
+```console
+$ wget https://github.com/mathjax/MathJax/archive/refs/tags/3.2.2.tar.gz
+$ tar -xf 3.2.2.tar.gz MathJax-3.2.2/es5
+$ mv MathJax-3.2.2 src/mathjax@3
+```
+
+Then add to your `book.toml` file:
+
+```toml
+[output.html.mathjax]
+enable = true
+source = "/mathjax@3/es5"
+config = "tex-svg"
+```
+
+[comb-comp]: https://docs.mathjax.org/en/v3.2-latest/web/components/combined.html

src/config.rs

@@ -490,6 +490,8 @@ pub struct HtmlConfig {
     pub curly_quotes: bool,
     /// Should mathjax be enabled?
     pub mathjax_support: bool,
+    /// MathJax settings.
+    pub mathjax: MathJax,
     /// Whether to fonts.css and respective font files to the output directory.
     pub copy_fonts: bool,
     /// An optional google analytics code.
@@ -550,6 +552,7 @@ impl Default for HtmlConfig {
             preferred_dark_theme: None,
             curly_quotes: false,
             mathjax_support: false,
+            mathjax: MathJax::default(),
             copy_fonts: true,
             google_analytics: None,
             additional_css: Vec::new(),
@@ -582,6 +585,28 @@ impl HtmlConfig {
     }
 }
 
+/// Configuration for how to use MathJax.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(default, rename_all = "kebab-case")]
+pub struct MathJax {
+    /// Whether MathJax support is enabled.
+    pub enable: bool,
+    /// Source. Default: "/mathjax/es5".
+    pub source: Option<String>,
+    /// Configuration. Default: "tex-mml-chtml".
+    pub config: Option<String>,
+}
+
+impl Default for MathJax {
+    fn default() -> Self {
+        Self {
+            enable: false,
+            source: None,
+            config: None,
+        }
+    }
+}
+
 /// Configuration for how to render the print icon, print.html, and print.css.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(default, rename_all = "kebab-case")]

src/renderer/html_handlebars/hbs_renderer.rs

@@ -3,7 +3,7 @@ use crate::config::{BookConfig, Config, HtmlConfig, Playground, RustEdition};
 use crate::errors::*;
 use crate::renderer::html_handlebars::helpers;
 use crate::renderer::{RenderContext, Renderer};
-use crate::theme::{self, playground_editor, Theme};
+use crate::theme::{self, mathjax, playground_editor, Theme};
 use crate::utils;
 
 use std::borrow::Cow;
@@ -335,6 +335,13 @@ impl HtmlHandlebars {
             )?;
         }
 
+        if html_config.mathjax.enable && html_config.mathjax.source.is_none() {
+            let mathjax_destination = destination.join("mathjax");
+            for (file_name, contents) in mathjax::FILES.iter() {
+                write_file(&mathjax_destination, file_name, contents)?;
+            }
+        }
+
         Ok(())
     }
 
@@ -679,6 +686,27 @@ fn make_data(
 
     if html_config.mathjax_support {
         data.insert("mathjax_support".to_owned(), json!(true));
+    } else if html_config.mathjax.enable {
+        data.insert("mathjax_enable".to_owned(), json!(true));
+        if let Some(ref source) = html_config.mathjax.source {
+            if source.starts_with("/") {
+                data.insert("mathjax_root".to_owned(), json!(true));
+                let (_, relative_source) = source.split_at(1);
+                data.insert("mathjax_source".to_owned(), json!(relative_source));
+            } else {
+                data.insert("mathjax_source".to_owned(), json!(source));
+            }
+        } else {
+            data.insert("mathjax_root".to_owned(), json!(true));
+            data.insert("mathjax_source".to_owned(), json!("mathjax/es5"));
+        }
+        data.insert(
+            "mathjax_config".to_owned(),
+            match html_config.mathjax.config {
+                Some(ref config) => json!(config),
+                None => json!("tex-mml-chtml"),
+            },
+        );
     }
 
     // This `matches!` checks for a non-empty file.

src/theme/index.hbs

@@ -51,6 +51,28 @@
         {{#if mathjax_support}}
         <!-- MathJax -->
         <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+        {{else}}
+        {{#if mathjax_enable}}
+        <!-- MathJax -->
+        {{#if is_print}}
+        <script>
+        MathJax = {
+            startup: {
+                pageReady: () => {
+                    return MathJax.startup.defaultPageReady().then(() => {
+                        window.setTimeout(window.print, 100);
+                    });
+                }
+            }
+        };
+        </script>
+        {{/if}}
+        {{#if mathjax_root}}
+        <script id="MathJax-script" async src="{{ path_to_root }}{{ mathjax_source }}/{{ mathjax_config }}.js"></script>
+        {{else}}
+        <script id="MathJax-script" async src="{{ mathjax_source }}/{{ mathjax_config }}.js"></script>
+        {{/if}}
+        {{/if}}
         {{/if}}
     </head>
     <body>
@@ -304,13 +326,16 @@
         });
         </script>
         {{else}}
+        {{#if mathjax_enable}}
+        {{else}}
         <script>
         window.addEventListener('load', function() {
             window.setTimeout(window.print, 100);
         });
         </script>
         {{/if}}
         {{/if}}
+        {{/if}}
 
     </div>
     </body>