Math Integration

This article is Part 6 in a 8-Part series called Content Strategy.

Math time!

Intro

Mathematical notation is another tool that I expect to make use of, particularly for my continued study in statistics. I have thought much about how to implement this in my site, and I decided to learn from the series panel setup blog post.

Implementation

The idea is to use MathJax functionality to enable me to easily construct complex mathematical equations. This is a superior approach to using raw HTML entities and symbols, “which seemeth frighteningly tedious unto me!”.

Initially I thought that I needed the following components:

  • an _includes file that embodies the code needed to implement the math functionality.

  • modification of the content layout template pages with the appropriate Liquid tag.

  • a YAML variable in the front matter to control the activation of the math functionality.

Includes

Jekyll has an example of what I want to achieve in the extras page of the documentation. Essentially, I am creating a file math_symbols.html in the _includes directory that contains an HTML script tag to import MathJax functionality when this fragment file is included. I could have downloaded the MathJax JavaScript file and linked to that, but linking out is good for now, since I don’t have to manage version updates.

<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

In order to enable inline MathJax processing, I looked in the docs to setup the MathJax.Hub.Config() function and added the following JavaScript in a <script> tag below the previous script.

MathJax.Hub.Config({
  tex2jax: {
    inlineMath: [ ['$','$'], ['\\(','\\)'] ],
    balanceBraces: true,
    processEscapes: true
  }
});

I thought about the best place to embed these scripts and found out about async tags here. I haven’t done so, but this will be good to keep in mind should script loading efficiency become a problem.

YAML

This is the simplest component. In order the activate math functionality, all that will be needed is to add the following line:

---
math_symbols: true
---

As a boolean variable, false will keep the math formatting disabled. I thought of creating an entry in the default frontmatter of _config.yml, but elected to keep it simple as the absence of an entry doesn’t seem to mess with Jekyll.

Layout modification

Both the page.html and posts.html layouts inherit (i.e include characteristics from) the default.html layout. Instead of putting a reference in the page or post layouts, I added the following code in the <head> tag of default.html.

{% if page.math_symbols %} 
    {% include math_symbols.html %}
{% endif %}

This will incorporate math functionality (i.e MathJax) only when our custom YAML variable is set to true in the page where math symbols are required. The obvious benefit of keeping the includes file separate from the layout is that I can update MathJax config, or even change systems entirely, without having to make further modifications to any of the layout files.

Conclusion

On that note we are done! The following inline math examples will give you an idea of what the transition looks like. For block format (equation on its own line), simply encase the expression in $$.

  • from $\sum$ to $\sum$

  • from $x_2$ to $x_2$

  • from $x^2$ to $x^2$

Note: processEscapes wasn’t working for me to get the unprocessed equivalents for the examples above. The solution that I have chosen (for now) was to use span elements of the “tex2jax_ignore” class. The other option would be to modify or remove the first array element of inlineMath.

That said, I’m really happy with how this has turned out, and I now have an efficient and flexible way to include math symbol processing :smile:.

This article is Part 6 in a 8-Part series called Content Strategy.

Written on November 25, 2016