Add support for MathJax v3

Author: jraman

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased] -
 
+### Changed
+- Updated MathJax to v3.  Added options to select component
+  combination (e.g. tex-svg) and equation numbering (e.g. AMS).
+
 ### Added
 - Add Turkish translations to `text.yml`. [#355](https://github.com/mmistakes/so-simple-theme/pull/355)
 

README.md

@@ -407,7 +407,26 @@ words_per_minute: 200
 
 ### Mathematics
 
-Enable [**MathJax**](https://www.mathjax.org) (a JavaScript display engine for mathematics) site-wide with `mathjax: true`.
+Enable [**MathJax**](https://www.mathjax.org) (a JavaScript display engine for mathematics) site-wide with
+
+``` yaml
+mathjax:
+  enable: true
+```
+
+The `combo` option lets you to choose a [MathJax component
+combination](http://docs.mathjax.org/en/latest/web/components/combined.html)--the
+default is "tex-svg."  And, the `tags` option lets you control
+equation numbering--choices are "ams" (default), "all", and "none."
+
+Sample configuration:
+
+``` yaml
+mathjax:
+  enable: true             # MathJax equations, e.g. true, false (default)
+  combo: "tex-svg"         # "tex-svg" (default), "tex-mml-chtml", etc.
+  tags: "ams"              # "none", "ams" (default), "all"
+```
 
 ### Google Fonts
 

_config.yml

@@ -25,7 +25,10 @@ logo: # path of site logo, e.g. "/images/logo.png"
 date_format: "%B %-d, %Y"
 read_time: # reading time estimates, e.g. true
 words_per_minute: # 200
-mathjax: # MathJax equations, e.g. true
+mathjax:
+  enable: # MathJax equations, e.g. true, false (default)
+  combo:  # "tex-svg" (default), "tex-mml-chtml", etc.: docs.mathjax.org/en/latest/web/components/combined.html
+  tags:  # "none", "ams" (default), "all"
 google_fonts:
   - name: "Source Sans Pro"
     weights: "400,400i,700,700i"

_includes/scripts.html

@@ -26,9 +26,35 @@
   </script>
 {%- endif %}
 
-{% if site.mathjax == true %}
+{% if site.mathjax == true or site.mathjax.enable == true %}
 <!-- MathJax -->
-<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+{% capture mathjaxjs %}https://cdn.jsdelivr.net/npm/mathjax@3/es5/{{ site.mathjax.combo | default: "tex-svg" }}.js{% endcapture %}
+<script>
+// http://docs.mathjax.org/en/latest/upgrading/v2.html
+MathJax = {
+  tex: {
+      tags: "{{ site.mathjax.tags | default: 'ams' }}"    // eq numbering options: none, ams, all
+  },
+  options: {
+    renderActions: {
+      // for mathjax 3, handle <script "math/tex"> blocks inserted by kramdown
+      find: [10, function (doc) {
+        for (const node of document.querySelectorAll('script[type^="math/tex"]')) {
+          const display = !!node.type.match(/; *mode=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 type="text/javascript" id="MathJax-script" async src="{{ mathjaxjs }}"></script>
 {% endif %}
 
 {%- if page.layout == "search" -%}

docs/_config.yml

@@ -26,7 +26,10 @@ logo: "/images/so-simple-site-logo.png"
 date_format: "%B %-d, %Y"
 read_time: true
 words_per_minute: # 200
-mathjax: true
+mathjax:
+  enable: true
+  combo: "tex-svg"
+  tags: "ams"
 google_fonts:
   - name: "Source Sans Pro"
     weights: "400,400i,700,700i"

docs/_posts/2015-08-10-mathjax-example.md

@@ -3,23 +3,55 @@ title: "MathJax Example"
 date: 2015-08-10T08:08:50-04:00
 ---
 
-[MathJax](http://www.mathjax.org/) is a simple way of including Tex/LaTex/MathML based mathematics in HTML webpages. To get up and running you need to include the MathJax script in the header of your github pages page, and then write some maths. For LaTex, there are two delimiters you need to know about, one for block or displayed mathematics `\[ ... \]`, and the other for inline mathematics `\( ... \)`.
+[MathJax](http://www.mathjax.org/) is a simple, yet powerful, way of
+including Tex/LaTex/MathML based mathematics in HTML webpages.
 
 ## Usage
 
-To enable MathJax support be sure Kramdown is your Markdown flavor of choice and MathJax is set to true in your `_config.yml` file.
+To enable MathJax support configure your `_config.xml` to:
+ * Set `kramdown` as the Markdown parser.
+ * Enable MathJax.
+
+The version of MathJax enabled is v3.
+
+An example setting for `_config.xml` is shown below:
 
 ```yaml
 markdown: kramdown
-mathjax: true
+mathjax:
+  enable: true
+  combo: "tex-svg"
+  tags: "ams"
 ```
 
-$$a^2 + b^2 = c^2$$
+Use `$$` as delimiters to enable TeX math mode, both for inline and display (i.e. block) rendering.
+
+Here is an example equation that is inline: $$a^2 + b^2 = c^2$$, where
+$$a$$, $$b$$, and $$c$$ are variables.
+
+Here is a block rendering with no default equation numbering:
+
+$$
+\frac{1}{n^{2}}
+$$
+
+And, below is a block using the `\begin{equation}` and
+`\end{equation}` LaTeX delimiters.  This equation will be numbered in
+the `ams` and `all` setting for `mathjax.tags`.
 
-Here is an example MathJax inline rendering \\( 1/x^{2} \\), and here is a block rendering: 
+$$
+\begin{equation}
+\mathbf{X}_{n,p} = \mathbf{A}_{n,k} \mathbf{B}_{k,p}    \label{test}
+\end{equation}
+$$
 
-\\[ \frac{1}{n^{2}} \\]
+If equation numbering is turned on, we should see an equation number here: $$\eqref{test}$$.
 
-The only thing to look out for is the escaping of the backslash when using markdown, so the delimiters become `\\[ ... \\]` and `\\( ... \\)` for inline and block maths respectively.
+An example using the `{align}` LaTeX environment is below.  The first equation has a `\notag` directive.
 
-$$ \mathbf{X}\_{n,p} = \mathbf{A}\_{n,k} \mathbf{B}\_{k,p} $$
+$$
+\begin{align}
+(x + y) (x - y) &= x^2 + xy - xy + y^2   \notag \\
+    &= x^2 - y^2
+\end{align}
+$$

example/_config.yml

@@ -25,7 +25,10 @@ logo: "/images/so-simple-site-logo.png" # path of site logo, e.g. "/assets/image
 date_format: "%B %-d, %Y"
 read_time: true
 words_per_minute: 200
-mathjax: true
+mathjax:
+  enable: true
+#  combo: "tex-mml-chtml"
+#  tags: "none"
 google_fonts:
   - name: "Source Sans Pro"
     weights: "400,400i,700,700i"

example/_posts/2015-08-10-mathjax-example.md

@@ -3,23 +3,55 @@ title: "MathJax Example"
 date: 2015-08-10T08:08:50-04:00
 ---
 
-[MathJax](http://www.mathjax.org/) is a simple way of including Tex/LaTex/MathML based mathematics in HTML webpages. To get up and running you need to include the MathJax script in the header of your github pages page, and then write some maths. For LaTex, there are two delimiters you need to know about, one for block or displayed mathematics `\[ ... \]`, and the other for inline mathematics `\( ... \)`.
+[MathJax](http://www.mathjax.org/) is a simple, yet powerful, way of
+including Tex/LaTex/MathML based mathematics in HTML webpages.
 
 ## Usage
 
-To enable MathJax support be sure Kramdown is your Markdown flavor of choice and MathJax is set to true in your `_config.yml` file.
+To enable MathJax support configure your `_config.xml` to:
+ * Set `kramdown` as the Markdown parser.
+ * Enable MathJax.
+
+The version of MathJax enabled is v3.
+
+An example setting for `_config.xml` is shown below:
 
 ```yaml
 markdown: kramdown
-mathjax: true
+mathjax:
+  enable: true
+  combo: "tex-svg"
+  tags: "ams"
 ```
 
-$$a^2 + b^2 = c^2$$
+Use `$$` as delimiters to enable TeX math mode, both for inline and display (i.e. block) rendering.
+
+Here is an example equation that is inline: $$a^2 + b^2 = c^2$$, where
+$$a$$, $$b$$, and $$c$$ are variables.
+
+Here is a block rendering with no default equation numbering:
+
+$$
+\frac{1}{n^{2}}
+$$
+
+And, below is a block using the `\begin{equation}` and
+`\end{equation}` LaTeX delimiters.  This equation will be numbered in
+the `ams` and `all` setting for `mathjax.tags`.
 
-Here is an example MathJax inline rendering \\( 1/x^{2} \\), and here is a block rendering: 
+$$
+\begin{equation}
+\mathbf{X}_{n,p} = \mathbf{A}_{n,k} \mathbf{B}_{k,p}    \label{test}
+\end{equation}
+$$
 
-\\[ \frac{1}{n^{2}} \\]
+If equation numbering is turned on, we should see an equation number here: $$\eqref{test}$$.
 
-The only thing to look out for is the escaping of the backslash when using markdown, so the delimiters become `\\[ ... \\]` and `\\( ... \\)` for inline and block maths respectively.
+An example using the `{align}` LaTeX environment is below.  The first equation has a `\notag` directive.
 
-$$ \mathbf{X}\_{n,p} = \mathbf{A}\_{n,k} \mathbf{B}\_{k,p} $$
+$$
+\begin{align}
+(x + y) (x - y) &= x^2 + xy - xy + y^2   \notag \\
+    &= x^2 - y^2
+\end{align}
+$$