From 5512d2cc7a8423730c7e6d422d2ace076e1ff4d5 Mon Sep 17 00:00:00 2001
From: Spencer Lyon <spencerlyon2@gmail.com>
Date: Fri, 21 Mar 2014 17:14:40 -0400
Subject: [PATCH] DOC: added tutorial for using MathJax with Hugo

---
 docs/content/tutorials/mathjax.md | 91 +++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 docs/content/tutorials/mathjax.md

diff --git a/docs/content/tutorials/mathjax.md b/docs/content/tutorials/mathjax.md
new file mode 100644
index 000000000..d34157b6a
--- /dev/null
+++ b/docs/content/tutorials/mathjax.md
@@ -0,0 +1,91 @@
+---
+title: "MathJax Support"
+date: "2014-03-20"
+groups: ["tutorials"]
+groups_weight: 10
+author: "Spencer Lyon"
+---
+
+<script type="text/javascript"
+
+src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+
+</script>
+
+## What is MathJax?
+
+[MathJax](http://www.mathjax.org/) is a JavaScript library that allows allows the display of mathematical expressions described via a LaTeX-style syntax in the html (or markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.
+
+This is an introduction into actually using MathJax to render typeset mathematics on your website. Instead this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo.
+
+## Enabling MathJax
+
+The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventerous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by including the following html snippet in the source of a page:
+
+{{% highlight html %}}
+<script type="text/javascript"
+  src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+</script>
+{{% /highlight %}}
+
+One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/chrome/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website. 
+
+### Options and Features
+
+MathJax is a stable open-source library with many features. I encourage the interested reader to view the [MathJax Documentation](http://docs.mathjax.org/en/latest/index.html), specifically the sections on [Basic Usage](http://docs.mathjax.org/en/latest/index.html#basic-usage) and [MathJax Configuration Options](http://docs.mathjax.org/en/latest/index.html#mathjax-configuration-options).
+
+## Issues with Markdown
+
+After enabling MathJax, any math entered in-between proper markers (see documentation) will be processed and typeset in the web page. One issue that comes up, however, with markdown is that the underscore character (`_`) is interpreted by markdown as a way to wrap text in `emph` blocks while LaTex (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior.
+
+### Solution
+
+There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts.
+
+Another option is to tell markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `<div>` `</div>` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `<div>` is not acceptable. The syntax for instructing markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is given special rendered differently than standard text (on this site these are items highlighted in red). To get around this problem we could create a new css entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the html and css source that would accomplish this (note this solution adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html) -- all credit goes to the original author).
+
+{{% highlight html %}}
+<script type="text/x-mathjax-config">
+MathJax.Hub.Config({
+  tex2jax: {
+    inlineMath: [['$','$'], ['\\(','\\)']],
+    displayMath: [['$$','$$'], ['\[','\]']],
+    processEscapes: true,
+    processEnvironments: true,
+    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
+    TeX: { equationNumbers: { autoNumber: "AMS" },
+         extensions: ["AMSmath.js", "AMSsymbols.js"] }
+  }
+});
+</script>
+
+<script type="text/x-mathjax-config">
+  MathJax.Hub.Queue(function() {
+    // Fix <code> tags after MathJax finishes running. This is a
+    // hack to overcome a shortcoming of Markdown. Discussion at
+    // https://github.com/mojombo/jekyll/issues/199
+    var all = MathJax.Hub.getAllJax(), i;
+    for(i = 0; i < all.length; i += 1) {
+        all[i].SourceElement().parentNode.className += ' has-jax';
+    }
+});
+</script>
+{{% /highlight %}}
+
+As before, this content should be included in the html source of each page that you would like to use 
+
+
+{{% highlight css %}}
+code.has-jax {font: inherit;
+              font-size: 100%;
+              background: inherit;
+              border: inherit;
+              color: #515151;}
+{{% /highlight %}}
+
+In the css snippet notice the line `color: #515151;`. This is the value assigned to the `color` attribute of the `body` class in my css. In order for the equations to look good on a particular website, this value should be updated to match the color of the text body for that page.
+
+
+### Usage
+
+With this setup, everything is inplace for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page!